felipemuhamed / docs

System-wide documents for dojot

dojot documentation

This repository contains the high-level documentation for dojot iot platform. For specific information regarding each of the sub-components that comprise the solution, please check the component's own documentation page.

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 Read The Docs own 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 source/conf.py build -d source/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:

1. Update the source files for the english version
2. Extract translatable messages from the english version

> make gettext

3. Update the message catalog (PO Files) for pt_BR language

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

4. Translate the messages in the pt_BR language PO files

This workflow is based on the internationalization feature of Sphinx.