How to build the documentation

The BrachioGraph documentation is intended to be of the highest possible quality. This is important for any project, and especially crucial in one with an educational purpose.

The basics

The documentation is written in Restructured Text, built with Sphinx and hosted at Read the Docs.

The documentation follows a system developed at Divio and described at https://www.divio.com/blog/documentation/, which strictly separates

• tutorials

• how-to guides

• reference material

• explanation

from each other.

Please keep that in mind when contributing any new documentation.

Working with the documentation locally

Install the required software

To build the documentation locally, cd into the docs directory and run:

make install

to install the required components into a new virtualenv.

Build the documentation

You can then execute:

make run

and you’ll find the documentation built at http://localhost:8004 (the port is set in docs/Makefile). The builder watches the documentation directory, so any saved changes will be immediately built.

Another option is to use:

make html

which will save the published HTML to docs/_build/html.

To run a spelling check:

make spelling

Contributing to the documentation

Documentation improvements and corrections can be submitted as pull requests.

Please check spelling, as described above. Any special words should be added to docs/spelling_wordlist. The documentation uses British English spelling.