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 uses the Diátaxis framework:
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.