Be more chatty about the customizable options in the README

README.md

@@ -2,15 +2,22 @@ Transparency: detail costs for libre price
 ==========================================
 
 It's still alpha-pre-ugly-looking and some strings are mentioning
-[FAImaison](https://faimaison.net), more usable version
-may be integrated to [coin](https://code.ffdn.org/ffdn/coin).
+[FAImaison](https://faimaison.net). A more usable version may be
+integrated to [coin](https://code.ffdn.org/ffdn/coin).
 
 Install it
 ----------
-Be sure to use python3.
+
+Be sure to use python3
 
     sudo apt-get install python virtualenv
+
+Create a dedicated virtualenv:
+
     virtualenv transparency_venv
+
+Clone this repository:
+
     git clone https://code.ffdn.org/jocelyn/transparency
     cd transparency
     source ../transparency_venv/bin/activate
@@ -20,10 +27,6 @@ Generate a secret key:
 
     echo SECRET_KEY=`python -c "import string,random; uni=string.ascii_letters+string.digits+string.punctuation; print(repr(''.join([random.SystemRandom().choice(uni) for i in range(random.randint(45,50))])))"` > transparency/local_settings.py
 
-Set your organization name :
-
-    echo 'ORGANIZATION_NAME="ACME Charity"' >> transparency/local_settings.py
-
 Create database:
 
     ./manage.py migrate
@@ -35,15 +38,119 @@ Create administrator account:
 Run it
 ------
 
-Run development server
+Activate your virtualenv if needed / if it is not already done:
+
+    source ../transparency_venv/bin/activate
+
+As far as you stay in development mode, you can activate `DEBUG` mode to
+avoid `settings.ALLOWED_HOSTS` error:
 
-    source ../transparency_venv/bin/activate # if it is not already done
     echo 'DEBUG=True' >> transparency/local_settings.py
+
+Please [read the Django deployment checklist][1] before trying to push
+your transparency website in production.
+
+[1]: https://docs.djangoproject.com/en/2.1/howto/deployment/checklist/
+
+Finally, run development server:
+
     ./manage.py runserver
 
 Use it
 ------
 
-- Enter data into (yeah, documentation can explain a bit better...)
+- Enter data into (yeah, documentation can explain a bit better…)
   http://localhost:8000/admin/
 - Browse http://localhost:8000 to view costs/details
+
+Custom settings
+---------------
+
+All your custom settings should go to the
+`transparency/local_settings.py` file. By default it does not exists,
+thus you have to create it (but if you follow the installation guide
+above, it is already there). As its extension proves, it is a regular
+python file. The basic way to add your customized option is just to list
+your variables and their values:
+
+```python
+MYVAR = "my custom value"
+```
+
+But, as it is a python file, you are free to do more complex stuff:
+
+```python
+import totallyotherpackage
+
+def my_custom_value_computation:
+    toto = "tata"
+    return toto + totallyotherpackage.funny_stuff()
+
+MYVAR = my_custom_value_computation()
+```
+
+The rest of this section present some of the available options you may
+want to customize to fit your needs:
+
+| Name                           | Description                                                                          | Default value         | Note                    |
+|--------------------------------|--------------------------------------------------------------------------------------|-----------------------|-------------------------|
+| `SECRET_KEY`                   | [Django secret key][2]. You should have set it during the setup, as described above. | `None`                | **required**            |
+| `DEBUG`                        | [Django debug mode][3]                                                               | `False`               | *development mode only* |
+| `ORGANIZATION_NAME`            | Name of your organization, for which you want to edit transparency reports.          | `"Transparency inc."` |                         |
+| `SETUP_COST_STAGGERING_MONTHS` | How many months do you want setup costs to be staggering accross                     | `36`                  |                         |
+| `PROVISIONING_DURATIONS`       | What provisionning durations will be available in the report forms.                  | See below             |                         |
+| `RESOURCES_UNITS`              | What resources units will be available in the report forms.                          | See below             |                         |
+
+[2]: https://docs.djangoproject.com/en/2.1/ref/settings/#std:setting-SECRET_KEY
+[3]: https://docs.djangoproject.com/en/2.1/ref/settings/#std:setting-DEBUG
+
+Both `PROVISIONING_DURATIONS` and `RESOURCES_UNITS` are lists of
+tuples. Their default values are respectively:
+
+```python
+PROVISIONING_DURATIONS = [
+    (datetime.timedelta(days=365*3), '3 ans'),
+    (datetime.timedelta(days=365*5), '5 ans'),
+]
+
+RESOURCES_UNITS = [
+    ('a', 'A'),
+    ('mbps', 'Mbps'),
+    ('u', 'U'),
+    ('ipv4', 'IPv4'),
+    ('eth', 'ports'),
+    ('services', 'abonnement')
+]
+```
+
+You can totally overwrite them:
+
+```python
+RESOURCES_UNITS = [
+    ('server', 'Serveurs'),
+    ('cube', 'Brique')
+]
+```
+
+Or just add new possibility, like this:
+
+```python
+PROVISIONING_DURATIONS.append((datetime.timedelta(days=182), '6 mois'))
+```
+
+or this:
+
+```python
+PROVISIONING_DURATIONS += [
+    (datetime.timedelta(days=182), '6 mois'),
+    (datetime.timedelta(days=365*8), '8 ans'),
+]
+```
+
+**Warning:** please note that the first element of each
+`RESOURCES_UNITS` tuple will be stored in the database as a string,
+which must be **10** characters long at most.
+
+You must note too, that the first element of each
+`PROVISIONING_DURATIONS` tuple should be a `datetime.timedelta` object
+or, at least, something having a `days` attribute, storing an integer.