[damned-lies] chore: update README content and use Markdown

[Claude Paroz <claudep src gnome org>]

commit bb6cdac3bed5f9c9af98f45210005eb1fecf0061
Author: Guillaume Bernard <associations guillaume-bernard fr>
Date:   Sat Apr 17 18:20:47 2021 +0200

    chore: update README content and use Markdown
    
    - use a Markdown syntax for the README file
    - update README contents to guide installation
    - move some comments from README to the
    requirements.txt file.

 README           | 148 -------------------------------------------------------
 README.md        | 133 +++++++++++++++++++++++++++++++++++++++++++++++++
 requirements.txt |  12 +++--
 3 files changed, 140 insertions(+), 153 deletions(-)
---
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..a0bf7be9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,133 @@
+# `damned-lies`
+
+`damned-lies` is a **translation-tracking Web application** originally aimed to help the GNOME Translation 
project. It is written in Python based on the [Django](https://www.djangoproject.com) framework.
+
+You can find the Data model in the `/docs` directory.
+
+## Requirements
+
+To run properly, `damned-lies` requires at least **Python 3.6** and **Django 3**.
+   
+Python dependencies are listed in the `requirements.txt` file alongside this README document. In order to 
install them, you will need to have the following dependencies installed:
+* **Debian-based systems**: `gettext intltool gnome-doc-utils itstool libmariadbclient-dev libicu-dev 
build-essential python3-dev`
+* **Fedora-based systems**: `gettext intltool gnome-doc-utils itstool mariadb-devel libicu-devel 
python-devel @development-tools @development-libraries`
+
+Note: `gnome-docs-utils` are used for stats generation.
+
+Then, you will be able to install dependencies using the `pip install -r requirements.txt` command.
+   
+### Optional requirements
+
+* You can install a debug bar which will give extra information about the current Django development.
+  ```bash
+  git clone git://github.com/jazzband/django-debug-toolbar.git
+  ```
+  Then, define `USE_DEBUG_TOOLBAR` to `True` in `damnedlies/local_settings.py` to use it.
+
+## Installation
+
+Once Python dependencies are installed, you will need some further steps in order to have a working 
environment.
+
+1. Create a `damnedlies/local_settings.py` and overwrite settings to match your requirements and your 
configuration layouts. Typical settings to customize include: `DATABASES`, `SECRET_KEY`, `DEBUG`, 
`STATIC_SERVE`, `ADMINS`, `ADMIN_GROUP`, `SITE_DOMAIN`, `SCRATCHDIR`, and various `EMAIL` settings.
+   
+   Please refer to Database configuration below for more information.
+
+   `SCRATCHDIR` should point to an existing directory, writable by the web application user.
+   
+   Create the `MEDIA_ROOT` directory, and the `upload` and `upload-backup` directories inside it, also 
writable by the web application user.
+
+   Note also that if you don’t want to really send mail when testing the app, you can set the 
`EMAIL_BACKEND` setting as follows to redirect mail to the console:
+   ```python
+   EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'
+   ```
+
+2. Run the following command to execute the database migrations:
+   ```bash
+   ./manage.py migrate
+   ```
+
+3.  In production, you will have to run the following command:
+    ```bash
+    ./manage.py collectstatic
+    ```
+
+    Then configure your Web server to statically serve this directory. For example, with the HTTPd server 
(*aka* Apache HTTP Server), a simple alias directive is enough:
+
+    ```apacheconf
+    Alias /static /absolute/path/to/djamnedlies/static
+    ```
+
+4. **Optionally**, if you want to populate the database with sample data, run:
+    ```bash
+    ./manage.py loaddata sample_data
+   ```
+
+5. You should now be able to launch the development server to check if all is running well:
+   ```bash
+    ./manage.py runserver
+   ```
+
+6. Configure Sites in admin interface (“View on site” link, site address in sent mail).
+
+## Running tests
+
+To execute the tests, run this command:
+```bash
+python manage.py test [optional path to run partial tests]
+```
+
+Read [the Django testing documentation](https://docs.djangoproject.com/en/stable/topics/testing/) for more 
details about testing in Django projects.
+
+## Maintenance tasks
+
+There is a management command to run maintenance tasks (clean never-activated accounts, inactivate unused 
roles, …):
+```bash
+./manage.py run-maintenance
+```
+Note: it might be useful to add the command in a cron schedule.
+
+## Databases
+
+It’s important to use the Unix Domain Socket connection to obtain good performances.
+
+### PostgreSQL
+
+In the `DATABASES['default']` dictionary, you just need to define `ENGINE = 
'django.db.backends.postgresql_psycopg2'` and the `NAME` key.
+Leave the `HOST` setting empty to use `UDS`.
+
+### MySQL
+
+Create a database in UTF8, either with `default-character-set = utf8` under `[mysqld]` section in the 
`my.cnf` file or with an explicit SQL instruction:
+
+```sql
+CREATE DATABASE <DATABASE_NAME> charset=utf8;
+```
+
+Then, you have to update your `damnedlies/local_settings.py`:
+
+```python
+DATABASES = {
+    'default' {
+        'ENGINE': 'django.db.backends.mysql',
+        'NAME': '<your database name>',
+        'USER': '<your user>',
+        'PASSWORD': '<your password>',
+        'HOST' = '/var/run/mysqld/mysqld.sock',
+        'OPTIONS' = {
+            'read_default_file': '/etc/mysql/my.cnf',
+        }
+    }
+}
+```
+
+Grep for `ANSI_QUOTES` in the source code to find the `models.py` which use a hack to workaround the double 
quotes interpretation in MySQL. The best solution is to run the MySQL server with the [`ANSI_QUOTES` 
mode](http://dev.mysql.com/doc/refman/5.7/en/sql-mode.html) (`sql-mode="ANSI_QUOTES"` in `my.cnf`), but it 
can be damaging for other applications.
+
+## Translations
+
+To be able to also extract strings from various database fields, a wrapper script has been created around 
the standard Django `makemessages` command. The script also copy po files in `/po` directory. 
+
+Run `python manage.py update-trans` to update translations when there are string changes.
+
+After translation files in po directory have been updated, there is another script to put back po files in 
`locale/<ll>/LC_MESSAGES/django.po` and call Django’s compile_messages command.
+
+Run `python manage.py compile-trans`.
diff --git a/requirements.txt b/requirements.txt
index 63452a32..083ba848 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,7 +1,9 @@
 django>=3,<4
-pillow
-mysqlclient
-django-debug-toolbar
-markdown==3.2.2
-pyicu==2.3.1  # 2.4.2 fails to compile on some platforms
+mysqlclient  # MySQL database connector
+pillow  # Hackergotchi check
+markdown==3.2.2  # Team presentation markup rendering
+pyicu==2.3.1  # Correct sorting in various languages. 2.4.2 fails to compile on some platforms
 translate-toolkit>=2.2.0
+
+# Debug tools
+django-debug-toolbar
\ No newline at end of file