Clean and reorganise a bit the documentation

docs/api.rst

@@ -4,8 +4,7 @@ The REST API
 All of what's possible to do with the website is also possible via a web API.
 This document explains how the API is organized and how you can query it.
 
-By default, the API talks JSON. There is no other way to speak with it
+The only supported data format is JSON.
-currently.
 
 Overall organisation
 ====================
@@ -13,7 +12,7 @@ Overall organisation
 You can access three different things: projects, members and bills. You can
 also get the balance for a project.
 
-For the examples, I'm using curl, feel free to use whatever you want to do the
+The examples here are using curl, feel free to use whatever you want to do the
 same thing, curl is not a requirement.
 
 Authentication
@@ -33,17 +32,17 @@ Projects
 You can't list projects, for security reasons. But you can create, update and
 delete one directly from the API.
 
-The URLs are `/api/projects` and `/api/projects/<identifier>`.
+The URLs are ``/api/projects`` and ``/api/projects/<identifier>``.
 
 Creating a project
 ~~~~~~~~~~~~~~~~~~
 
 A project needs the following arguments:
 
-* `name`: The project name (string)
+* ``name``: The project name (string)
-* `id`: the project identifier (string without special chars or spaces)
+* ``id``: the project identifier (string without special chars or spaces)
-* `password`: the project password / secret code (string)
+* ``password``: the project password / secret code (string)
-* `contact_email`: the contact email
+* ``contact_email``: the contact email
 
 ::
 
@@ -85,7 +84,7 @@ Getting information about the project::
 Updating a project
 ~~~~~~~~~~~~~~~~~~
 
-Updating a project is done with the `PUT` verb::
+Updating a project is done with the ``PUT`` verb::
 
     $ curl --basic -u yay:yay -X PUT\
     https://ihatemoney.org/api/projects/yay -d\
@@ -101,7 +100,7 @@ Just send a DELETE request ont the project URI ::
 Members
 -------
 
-You can get all the members with a `GET` on `/api/projects/<id>/members`::
+You can get all the members with a ``GET`` on ``/api/projects/<id>/members``::
 
     $ curl --basic -u demo:demo https://ihatemoney.org/api/projects/demo/members\
     [{"weight": 1, "activated": true, "id": 31, "name": "Arnaud"},
@@ -109,20 +108,21 @@ You can get all the members with a `GET` on `/api/projects/<id>/members`::
      {"weight": 1, "activated": true, "id": 33, "name": "Olivier"},
      {"weight": 1, "activated": true, "id": 34, "name": "Fred"}]
 
-Add a member with a `POST` request on `/api/projects/<id>/members`::
+Add a member with a ``POST`` request on ``/api/projects/<id>/members``::
 
     $ curl --basic -u demo:demo -X POST\
     https://ihatemoney.org/api/projects/demo/members -d 'name=tatayoyo'
     35
 
-You can also `PUT` a new version of a member (changing its name)::
+You can also ``PUT`` a new version of a member (changing its name)::
 
     $ curl --basic -u demo:demo -X PUT\
     https://ihatemoney.org/api/projects/demo/members/36\
     -d 'name=yeaaaaah'
     {"activated": true, "id": 36, "name": "yeaaaaah", "weight": 1}
 
-Delete a member with a `DELETE` request on `/api/projects/<id>/members/<member-id>`::
+Delete a member with a ``DELETE`` request on
+``/api/projects/<id>/members/<member-id>``::
 
     $ curl --basic -u demo:demo -X DELETE\
     https://ihatemoney.org/api/projects/demo/members/35
@@ -131,18 +131,21 @@ Delete a member with a `DELETE` request on `/api/projects/<id>/members/<member-i
 Bills
 -----
 
-You can get the list of bills by doing a `GET` on `/api/projects/<id>/bills` ::
+You can get the list of bills by doing a ``GET`` on
+``/api/projects/<id>/bills`` ::
 
     $ curl --basic -u demo:demo https://ihatemoney.org/api/projects/demo/bills
 
-Add a bill with a `POST` query on `/api/projects/<id>/bills`. you need the
+Add a bill with a ``POST`` query on ``/api/projects/<id>/bills``. you need the
 following params:
 
-* `date`: the date of the bill; defaults to current date if not provided. (yyyy-mm-dd)
+* ``date``: the date of the bill; defaults to current date if not
-* `what`: what have been payed
+  provided. (format is ``yyyy-mm-dd``)
-* `payer`: by who ? (id)
+* ``what``: what have been payed
-* `payed_for`: for who ? (id, to set multiple id use a list, e.g. `["id1", "id2"]`)
+* ``payer``: by who ? (id)
-* `amount`: amount payed
+* ``payed_for``: for who ? (id, to set multiple id use a list,
+  e.g. ``["id1", "id2"]``)
+* ``amount``: amount payed
 
 Returns the id of the created bill ::
 
@@ -151,15 +154,16 @@ Returns the id of the created bill ::
     -d "date=2011-09-10&what=raclette&payer=31&payed_for=31&amount=200"
     80
 
-You can also `PUT` a new version of the bill at
+You can also ``PUT`` a new version of the bill at
-`/api/projects/<id>/bills/<bill-id>`::
+``/api/projects/<id>/bills/<bill-id>``::
 
     $ curl --basic -u demo:demo -X PUT\
     https://ihatemoney.org/api/projects/demo/bills/80\
     -d "date=2011-09-10&what=raclette&payer=31&payed_for=31&amount=250"
     80
 
-And you can of course `DELETE` them at `/api/projects/<id>/bills/<bill-id>`::
+And you can of course ``DELETE`` them at
+``/api/projects/<id>/bills/<bill-id>``::
 
     $ curl --basic -u demo:demo -X DELETE\
     https://ihatemoney.org/api/projects/demo/bills/80\
@@ -169,7 +173,8 @@ And you can of course `DELETE` them at `/api/projects/<id>/bills/<bill-id>`::
 Statistics
 ----------
 
-You can get some project stats with a `GET` on `/api/projects/<id>/statistics`::
+You can get some project stats with a ``GET`` on
+``/api/projects/<id>/statistics``::
 
     $ curl --basic -u demo:demo https://ihatemoney.org/api/projects/demo/statistics
     [

docs/configuration.rst

@@ -0,0 +1,122 @@
+.. _configuration:
+
+Configuration
+=============
+
+"ihatemoney" relies on a configuration file. If you run the application for the
+first time, you will need to take a few moments to configure the application
+properly.
+
+The default values given here are those for the development mode.
+To know defaults on your deployed instance, simply look at your
+``ihatemoney.cfg`` file.
+
+"Production values" are the recommended values for use in production.
+
+`SQLALCHEMY_DATABASE_URI`
+-------------------------
+
+Specifies the type of backend to use and its location. More information on the
+format used can be found on `the SQLAlchemy documentation`_.
+
+- **Default value:** ``sqlite:///tmp/ihatemoney.db``
+- **Production value:** Set it to some path on your disk. Typically
+  ``sqlite:///home/ihatemoney/ihatemoney.db``. Do *not* store it under
+  ``/tmp`` as this folder is cleared at each boot.
+
+If you're using PostgreSQL, Your client must use utf8. Unfortunately,
+PostgreSQL default is to use ASCII. Either change your client settings,
+or specify the encoding by appending ``?client_encoding=utf8`` to the
+connection string.
+
+`SECRET_KEY`
+------------
+
+The secret key used to encrypt the cookies.
+
+- **Production value:** `ihatemoney conf-example ihatemoney.cfg` sets it to
+  something random, which is good.
+
+`MAIL_DEFAULT_SENDER`
+---------------------
+
+A python tuple describing the name and email address to use when sending
+emails.
+
+- **Default value:** ``("Budget manager", "budget@notmyidea.org")``
+- **Production value:** Any tuple you want.
+
+`ACTIVATE_DEMO_PROJECT`
+-----------------------
+
+If set to `True`, a demo project will be available on the frontpage.
+
+- **Default value:** ``True``
+- **Production value:** Usually, you will want to set it to ``False`` for a
+  private instance.
+
+`ADMIN_PASSWORD`
+----------------
+
+Hashed password to access protected endpoints. If left empty, all
+administrative tasks are disabled.
+
+- **Default value:** ``""`` (empty string)
+- **Production value:** To generate the proper password HASH, use
+  ``ihatemoney generate_password_hash`` and copy the output into the value of
+  *ADMIN_PASSWORD*.
+
+`ALLOW_PUBLIC_PROJECT_CREATION`
+-------------------------------
+
+If set to ``True``, everyone can create a project without entering the admin
+password. If set to ``False``, the password needs to be entered (and as such,
+defined in the settings).
+
+- **Default value:** : ``True``.
+
+
+`ACTIVATE_ADMIN_DASHBOARD`
+--------------------------
+
+If set to `True`, the dashboard will become accessible entering the admin
+password, if set to `True`, a non empty ADMIN_PASSWORD needs to be set.
+
+- **Default value**: ``False``
+
+`APPLICATION_ROOT`
+------------------
+
+If empty, ihatemoney will be served at domain root (e.g: *http://domain.tld*),
+if set to ``"somestring"``, it will be served from a "folder"
+(e.g: *http://domain.tld/somestring*).
+
+- **Default value:** ``""`` (empty string)
+
+.. _the SQLAlchemy documentation: http://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls
+
+Configuring emails sending
+--------------------------
+
+By default, Ihatemoney sends emails using a local SMTP server, but it's
+possible to configure it to act differently, thanks to the great
+`Flask-Mail project <https://pythonhosted.org/flask-mail/#configuring-flask-mail>`_
+
+* **MAIL_SERVER** : default **'localhost'**
+* **MAIL_PORT** : default **25**
+* **MAIL_USE_TLS** : default **False**
+* **MAIL_USE_SSL** : default **False**
+* **MAIL_DEBUG** : default **app.debug**
+* **MAIL_USERNAME** : default **None**
+* **MAIL_PASSWORD** : default **None**
+* **DEFAULT_MAIL_SENDER** : default **None**
+
+Using an alternate settings path
+--------------------------------
+
+You can put your settings file where you want, and pass its path to the
+application using the ``IHATEMONEY_SETTINGS_FILE_PATH`` environment variable.
+
+For instance ::
+
+    export IHATEMONEY_SETTINGS_FILE_PATH="/path/to/your/conf/file.cfg"

docs/contributing.rst

@@ -49,16 +49,18 @@ In case you want to update to newer versions (from git), you can just run the "u
 Create database migrations
 --------------------------
 
-In case you need to modify the database schema, first update the models in ihatemoney/models.py.
+In case you need to modify the database schema, first update the models in
-Then run the following command to create a new database revision file::
+``ihatemoney/models.py``. Then run the following command to create a new
+database revision file::
 
   make create-database-revision
 
 If your changes are simple enough, the generated script will be populated with
-the necessary migrations steps. You can edit the generated script. eg: to add data migrations.
+the necessary migrations steps. You can edit the generated script. eg: to add
+data migrations.
 
-For complex migrations, it is recommended to start from an empty revision file which can be created
+For complex migrations, it is recommended to start from an empty revision file
-with the following command::
+which can be created with the following command::
 
   make create-empty-database-revision
 
@@ -75,7 +77,7 @@ You can also set the `TESTING` flag to `True` so no mails are sent
 (and no exception is raised) while you're on development mode.
 Then before running the application, declare its path with ::
 
-    $ export IHATEMONEY_SETTINGS_FILE_PATH="$(pwd)/settings.cfg"
+  export IHATEMONEY_SETTINGS_FILE_PATH="$(pwd)/settings.cfg"
 
 How to contribute
 =================
@@ -89,8 +91,8 @@ a developer or an user.
 As a developer
 --------------
 
-If you want to contribute code, you can write it and then issue a pull request on
+If you want to contribute code, you can write it and then issue a pull request
-github. Please, think about updating and running the tests before asking for
+on github. Please, think about updating and running the tests before asking for
 a pull request as it will help us to maintain the code clean and running.
 
 To do so::
@@ -109,14 +111,14 @@ As a translator
 
 Collect all new strings to translate::
 
-  $ make update-translations
+  make update-translations
 
- Add missing translations to *.po* files inside *translations/* dir using your
+Add missing translations to *.po* files inside *translations/* dir using your
- favorite text editor.
+favorite text editor.
 
- Compile them into *.mo* files::
+Compile them into *.mo* files::
 
-  $ make build-translations
+  make build-translations
 
 Commit both *.mo* and *.po*.
 
@@ -125,8 +127,8 @@ End-user
 
 You are using the application and found a bug? You have some ideas about how to
 improve the project? Please tell us `by filling a new issue <https://github.com/spiral-project/ihatemoney/issues>`_.
-Or, if you prefer, you can send me an email to `alexis@notmyidea.org` and I will
+Or, if you prefer, you can send me an email to `alexis@notmyidea.org` and I
-update the issue tracker with your feedback.
+will update the issue tracker with your feedback.
 
 Thanks again!
 
@@ -154,22 +156,18 @@ In order to prepare a new release, we are following the following steps:
 - Merge remaining pull requests;
 - Update :file:`CHANGELOG.rst` with the last changes;
 - Update :file:`CONTRIBUTORS`;
-- Update known good versions of dependencies in ``requirements.txt`` with this command (from inside the venv):
+- Update known good versions of dependencies in ``requirements.txt`` with this
+  command (from inside the venv)::
 
-.. code-block:: bash
+    make build-requirements
 
-     $ make build-requirements
+- If needed, recompress assets. It requires zopflipng::
-- If needed, recompress assets. It requires zopflipng:
 
-.. code-block:: bash
+    make compress-assets
 
-     $ make compress-assets
+Once this is done, use the "release" instruction::
 
-Once this is done, use the "release" instruction:
+    make release
-
-.. code-block:: bash
-
-     $ make release
 
 And the new version should be published on PyPI.
 

docs/index.rst

@@ -5,6 +5,9 @@ I hate money
 It keeps track of who bought what, when, and for whom; and helps to settle the
 bills.
 
+I hate money is written in python, using the `flask <https://palletsprojects.com/p/flask/>`_
+framework. It's developped with ease of use in mind, and is trying to
+keep things simple. Hope you (will) like it!
 
 Table of content
 ================
@@ -13,6 +16,7 @@ Table of content
    :maxdepth: 1
 
    installation
+   configuration
    upgrade
    api
    contributing

docs/installation.rst

@@ -2,8 +2,8 @@ Installation
 ############
 
 We lack some knowledge about packaging to make Ihatemoney installable on mainstream
-Linux distributions. If you want to give us a hand on the topic, please check-out
+Linux distributions. If you want to give us a hand on the topic, please
-`the issue about debian packaging <https://github.com/spiral-project/ihatemoney/issues/227>`_.
+check-out `the issue about debian packaging <https://github.com/spiral-project/ihatemoney/issues/227>`_.
 
 If you are using Yunohost (a server operating system aiming to make self-hosting accessible to anyone),
 you can use the `Ihatemoney package <https://github.com/YunoHost-Apps/ihatemoney_ynh>`_.
@@ -98,8 +98,8 @@ Deploy it
 Now, if you want to deploy it on your own server, you have many options.
 Three of them are documented at the moment.
 
-*Of course, if you want to contribute another configuration, feel free to open a
+*Of course, if you want to contribute another configuration, feel free
-pull-request against this repository!*
+to open a pull-request against this repository!*
 
 
 Whatever your installation option is…
@@ -114,8 +114,8 @@ Whatever your installation option is…
     ihatemoney generate-config ihatemoney.cfg > /etc/ihatemoney/ihatemoney.cfg
     chmod 740 /etc/ihatemoney/ihatemoney.cfg
 
-You probably want to adjust `/etc/ihatemoney/ihatemoney.cfg` contents, you may
+You probably want to adjust ``/etc/ihatemoney/ihatemoney.cfg`` contents,
-do it later, see `Configuration`_.
+you may do it later, see :ref:`configuration`.
 
 
 With Apache and mod_wsgi
@@ -126,8 +126,11 @@ With Apache and mod_wsgi
      chgrp www-data /etc/ihatemoney/ihatemoney.cfg
      chown www-data /var/lib/ihatemoney
 
-2. Install Apache and mod_wsgi - libapache2-mod-wsgi(-py3) for Debian based and mod_wsgi for RedHat based distributions -
+2. Install Apache and mod_wsgi : ``libapache2-mod-wsgi(-py3)`` for Debian
-3. Create an Apache virtual host, the command ``ihatemoney generate-config apache-vhost.conf`` will output a good starting point (read and adapt it)
+   based and ``mod_wsgi`` for RedHat based distributions
+3. Create an Apache virtual host, the command
+   ``ihatemoney generate-config apache-vhost.conf`` will output a good
+   starting point (read and adapt it).
 4. Activate the virtual host if needed and restart Apache
 
 With Nginx, Gunicorn and Supervisord/systemd
@@ -180,13 +183,15 @@ Install Gunicorn::
        systemctl enable ihatemoney.service
        systemctl start ihatemoney.service
 
-4. Copy (and adapt) output of ``ihatemoney generate-config nginx.conf`` with your nginx vhosts [#nginx-vhosts]_
+4. Copy (and adapt) output of ``ihatemoney generate-config nginx.conf``
+   with your nginx vhosts [#nginx-vhosts]_
 5. Reload nginx (and supervisord if you use it). It should be working ;)
 
 .. [#nginx-vhosts] typically, */etc/nginx/conf.d/* or
    */etc/nginx/sites-available*, depending on your distribution.
 
-.. [#systemd-services] ``/etc/systemd/system/ihatemoney.service`` path may change depending on your distribution.
+.. [#systemd-services] ``/etc/systemd/system/ihatemoney.service``
+                       path may change depending on your distribution.
 
 With Docker
 -----------
@@ -202,7 +207,8 @@ Start a daemonized Ihatemoney container::
 Ihatemoney is now available on http://localhost:8000.
 
 All Ihatemoney settings can be passed with ``-e`` parameters
-e.g. with a secure ``SECRET_KEY``, an external mail server and an external database::
+e.g. with a secure ``SECRET_KEY``, an external mail server and an
+external database::
 
     docker run -d -p 8000:8000 \
     -e SECRET_KEY="supersecure" \
@@ -218,127 +224,8 @@ A volume can also be specified to persist the default database file::
 
     docker run -d -p 8000:8000 -v /host/path/to/database:/database ihatemoney
 
-Additional gunicorn parameters can be passed using the docker ``CMD`` parameter.
+Additional gunicorn parameters can be passed using the docker ``CMD``
+parameter.
 For example, use the following command to add more gunicorn workers::
 
     docker run -d -p 8000:8000 ihatemoney -w 3
-
-.. _configuration:
-
-Configuration
-=============
-
-ihatemoney relies on a configuration file. If you run the application for the
-first time, you will need to take a few moments to configure the application
-properly.
-
-Defaults given here, are those for development mode. To know defaults on your
-deployed instance, simply look at your *ihatemoney.cfg*.
-
-Production values are recommended values for use in production.
-
-`SQLALCHEMY_DATABASE_URI`
--------------------------
-
-Specifies the type of backend to use and its location. More information on the
-format used can be found on `the SQLAlchemy documentation`_.
-
-- **default value:** ``sqlite:///tmp/ihatemoney.db``
-- **Production value:** Set it to some path on your disk. Typically
-  ``sqlite:///home/ihatemoney/ihatemoney.db``. Do *not* store it under
-  ``/tmp`` as this folder is cleared at each boot.
-
-If you're using PostgreSQL, Your client must use utf8. Unfortunately, PostgreSQL default
-is to use ASCII. Either change your client settings, or specify the encoding by appending
-`?client_encoding=utf8` to the connection string.
-
-`SECRET_KEY`
-------------
-
-The secret key used to encrypt the cookies.
-
-- **Production value:** `ihatemoney conf-example ihatemoney.cfg` sets it to
-  something random, which is good.
-
-`MAIL_DEFAULT_SENDER`
----------------------
-
-A python tuple describing the name and email address to use when sending emails.
-
-- **Default value:** ``("Budget manager", "budget@notmyidea.org")``
-- **Production value:** Any tuple you want.
-
-`ACTIVATE_DEMO_PROJECT`
------------------------
-
-If set to `True`, a demo project will be available on the frontpage.
-
-- **Default value:** ``True``
-- **Production value:** Usually, you will want to set it to ``False`` for a
-  private instance.
-
-`ADMIN_PASSWORD`
-----------------
-
-Hashed password to access protected endpoints. If left empty, all administrative
-tasks are disabled.
-
-- **Default value:** ``""`` (empty string)
-- **Production value:** To generate the proper password HASH, use
-  ``ihatemoney generate_password_hash`` and copy the output into the value of
-  *ADMIN_PASSWORD*.
-
-`ALLOW_PUBLIC_PROJECT_CREATION`
--------------------------------
-
-If set to ``True``, everyone can create a project without entering the admin
-password. If set to ``False``, the password needs to be entered (and as such,
-defined in the settings).
-
-- **Default value:** : ``True``.
-
-
-`ACTIVATE_ADMIN_DASHBOARD`
---------------------------
-
-If set to `True`, the dashboard will become accessible entering the admin
-password, if set to `True`, a non empty ADMIN_PASSWORD needs to be set.
-
-- **Default value**: ``False``
-
-`APPLICATION_ROOT`
-------------------
-
-If empty, ihatemoney will be served at domain root (e.g: *http://domain.tld*),
-if set to ``"somestring"``, it will be served from a "folder"
-(e.g: *http://domain.tld/somestring*).
-
-- **Default value:** ``""`` (empty string)
-
-.. _the SQLAlchemy documentation: http://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls
-
-Configuring emails sending
---------------------------
-
-By default, Ihatemoney sends emails using a local SMTP server, but it's
-possible to configure it to act differently, thanks to the great
-`Flask-Mail project <https://pythonhosted.org/flask-mail/#configuring-flask-mail>`_
-
-* **MAIL_SERVER** : default **'localhost'**
-* **MAIL_PORT** : default **25**
-* **MAIL_USE_TLS** : default **False**
-* **MAIL_USE_SSL** : default **False**
-* **MAIL_DEBUG** : default **app.debug**
-* **MAIL_USERNAME** : default **None**
-* **MAIL_PASSWORD** : default **None**
-* **DEFAULT_MAIL_SENDER** : default **None**
-
-Using an alternate settings path
---------------------------------
-
-You can put your settings file where you want, and pass its path to the
-application using the ``IHATEMONEY_SETTINGS_FILE_PATH`` environment variable.
-
-e.g.::
-
-    $ export IHATEMONEY_SETTINGS_FILE_PATH="/path/to/your/conf/file.cfg"

docs/upgrade.rst

@@ -66,7 +66,8 @@ development only.
 
     pip install ihatemoney
 
-3. Fix your configuration file (paths *have* changed), depending on the software you use in your setup:
+3. Fix your configuration file (paths *have* changed), depending on
+   the software you use in your setup:
 
    - **gunicorn**: ``ihatemoney generate-config gunicorn.conf.py`` (nothing
      critical changed, keeping your old config might be fine)