Building the Documentation

Prerequisites

The documentation build process uses Doxygen and Sphinx along with a few extensions.

If you’re using Conda, the required software can be installed in a single line:

conda install -c conda-forge --file ci/conda_env_sphinx.yml

Otherwise, you’ll first need to install Doxygen yourself (for example from your distribution’s official repositories, if using Linux). Then you can install the Python-based requirements with the following command:

pip install -r docs/requirements.txt

Building

Note

If you are building the documentation on Windows, not all sections may build properly.

These two steps are mandatory and must be executed in order.

  1. Process the C++ API using Doxygen

    pushd cpp/apidoc
    doxygen
    popd
    
  2. Build the complete documentation using Sphinx

    pushd docs
    make html
    popd
    

After these steps are completed, the documentation is rendered in HTML format in docs/_build/html. In particular, you can point your browser at docs/_build/html/index.html to read the docs and review any changes you made.

Building with Docker

You can use Docker to build the documentation:

docker-compose build cpp
docker-compose build python
docker-compose build docs
docker-compose run docs

The final output is located under docs/_build/html.