translate documentation¶

If you have a local clone of this repository and you want to change the documentation, then you should follow this simple guide.

Build¶

The readable version of this documentation can be generated by means of sphinx. In order to do so, please follow the steps below. Those are actually based off ReadTheDocs documentation.

pip install sphinx sphinx-autobuild sphinx_rtd_theme sphinx-intl
make html

For that to work, you must have pip installed on the machine used to build the documentation. To install pip on an Ubuntu machine:

sudo apt-get install python-pip

To build the documentation in Brazilian Portuguese language, run the following extra commands:

sphinx-intl -c conf.py build -d locale
make html BUILDDIR=build/html-pt_BR O='-d build/doctrees/ -D language=pt_BR'

Update workflow¶

To update the documentation, follow the steps below:

Update the source files for the english version
Extract translatable messages from the english version

make gettext

Update the message catalog (PO Files) for pt_BR language

sphinx-intl -c conf.py update -p build/gettext -l pt_BR

Translate the messages in the pt_BR language PO files

This workflow is based on the Sphinx i18n guide.