Building the documentation

Prerequisites

The documentation system of PandaRoot relies on two different external programs. The first one is doxygen which is used to extract the comments written in the source files to generate an API documentation. The second external program is sphinx which is used to generate a nice looking webpage which contains also the manuals written in the docs folder. Sphinx uses in addition breathe which allows to incorporate the doxygen generated documentation into the sphinx web-pages. For Sphinx to work you need to have python3 installed in your system.

Doxygen

You can grab the files to install doxygen from the official download page and install it.

Sphinx

The official instructions offer different ways for installation. Take the one you prefer.

Read the Docs Sphinx Theme

The PandaRoot documentation uses the “Read the Docs” theme which has to be installed via pip:

pip install sphinx_rtd_theme

Breathe

Breathe is the bridge between doxygen and Sphinx and can be installed via pip:

pip install breathe

MyST parser

MyST is the bridge between md files and Sphinx and can be installed via pip:

pip install myst-parser

Graphviz

Graphviz can be used by Sphinx for plotting.

Generating the documentation

The documentation can be created via two cmake calls. The first creates the doxygen documentation:

cmake --build ./build --target doxygen

The second one creates the sphinx part of the documentation:

cmake --build ./build --target sphinx

The output is stored in <build_folder>/docs/doxygen resp. <build_folder>/docs/sphinx. Opening the index.html file in one of the folders with an html browser shows the start page of the documentation.

Sphinx in Visual Studio Code

VS Code is a free integrated development platform which offers many extensions and can handle git, cmake, c++, python, jupyter notebooks and even rudimentary root file access.

Also for our documentation you may use VS Code to create a quick preview of what you are editing. After installing spinx etc. like above you can install in VS Code the “Extension Pack for reStructuredText” and subsequently some dependencies (e.g. esbonio language server) announced by the notification pop-ups. The preview can be opened by a button at the top right corner of the file editor tab.

The .rst file you’re editing has to be stored in our docs/ folder and should be included in a table of content. The artifacts, i.e. the index.html to check links in a browser, can be found then in docs/_build/ by default.