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.
Pre-built HTML and PDF versions of the documentation are available at Read the Docs.
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/
.