social-doc/README.sphinx.md

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.