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.
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
export READTHEDOCS_VERSION=latest
make html
The `READTHEDOCS_VERSION`
environment variable should be set to the component
version being built, such as `latest`
or `0.2.0`
. In the automated build process from readthedocs, this exact variable will be set as the name of the branch/tag being built.
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.