Documentation Build Instructions
This project uses Sphinx to generate documentation from reStructuredText and CommonMark (Markdown) files under doc/
. It also uses Doxygen to generate documentation out of the project's source code.
To build the documentation (useful for people wishing to contribute to it), it is highly recommended to setup a Python virtual environment where the necessary packages (docutils, sphinx, etc.) can be installed via pip and be kept at a specific version. You will also need to install Doxygen.
The following steps illustrate how to do this on a Debian/Ubuntu Linux box, with the virtual environment placed inside the doc/
folder of the project itself:
$> sudo apt install doxygen virtualenv
$> cd doc
$> virtualenv build_env
$> . build_env/bin/activate
$> pip install -r requirements.txt
$> deactivate
Note: If you use the same folder name and location (doc/build_env
) for the virtual environment as in the above example, there is already a gitignore rule in place that will not track any auto-generated files within that folder.
Once the environment is installed, you can (re)build the documentation by doing:
$> cd doc
$> . build_env/bin/activate
$> make html
$> deactivate
The generated documentation can be accessed by opening doc/_build/html/index.html
in your browser.
Alternatively, if you have LaTeX installed, you can produce a PDF by doing:
$> cd doc
$> . build_env/bin/activate
$> make latexpdf
$> deactivate
The generated documentation can be accessed by opening the PDF found under doc/_build/latex/
.