Install Sphinx
--------------
Install Sphinx from Debian repositories:

    apt-get install python-sphinx

Install Sphinx using virtualenv (assumes virtualenv is already installed):

    virtualenv venv
    source venv/bin/activate
    pip install -r requirements.txt


Build Documentation
-------------------
The documentation can be generated using the following commands

    cd docs/
    make html

The documentation should now be available in `_build/` directory under the
`docs/` directory.

To generate the Spanish translations:

    cd docs/
    make translations

The Spanish version will be generated in `docs/_build/spanish`.

New Pages and Internationalisation
----------------------------------
Translation works using `sphinx-intl`. It creates .po files where English phrases can be converted to other languages.

To add a page and create the .po file for translation:

1. Set up the virtualenv as described above. Activate it and install the requirements.
2. Create a new file for the page such as `admin/file.rst`.
3. Edit it and make it correct in English (`make html`).
4. Open terminal to `/docs` and run `make gettext`. This creates files under `_build/locale`
5. Run `sphinx-intl update -p _build/locale/ -l es` to refresh the .po files
6. Edit .po files under `locale/es/LC_MESSAGES/...`
7. Run `make translations` to generate the Spanish version
8. Commit changes.

