How to build/update/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.
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'
To update the documentation, follow the steps below:
- Update the source files for the english version
- Extract translatable messages from the english version
- 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.