Building the Documentation locally

The documentation consists of two independent parts. The Doxygen-based C++ API documentation and these Sphinx user guides.

First Steps

All following commands are executed from the ~/bioscara/docs/ directory:

cd docs

Create the Virtual Environment and Install Dependencies

It is recommended to use a virtual environment to manage all dependencies. These steps need to be executed only once at the first time. Create the virtual python environment:

python -m venv .venv

Before installing the dependencies the environment needs to be activated:

source .venv/bin/activate

The we can install the required packages to build the documentation:

pip install -r requirements-docs.txt

This installs Sphinx and its packages.

Aditionally install doxygen

sudo apt-get update
sudo apt-get install doxygen

And install all LaTeX tools:

sudo apt-get install texlive texlive-font-utils texlive-fonts-recommended texlive-latex-extra latexmk

Building the Documentation

First make sure the virtual environment is activated:

source .venv/bin/activate

Then run doxygen from the docs/doxygen/ directory to produce HTML, XML and LaTeX output:

cd doxygen
doxygen

Compile the LaTeX to a PDF:

cd doxygen/latex
make

First compile it as a PDF (the HTML will link to it later)

sphinx-build -M latexpdf . sphinx/latex

Finally build the Sphinx documentation:

sphinx-build -b html . sphinx/html