Documentation

The firmware documentation is currently a mix of Sphinx and Doxygen.

This means:

  • Regular Javadoc-style in-code comments.

  • a number of restructured text (RST) files in the /docs/texts directory

  • Doxygen API docs built at /docs/doxygen

  • Sphinx docs built at /docs/sphinx using Breathe to read in doxygen documentation.

Doxygen provides a very good cross-reference for C++ code which can replace an IDE and makes it easy to dig into the code in particular for people not familiar with it. However, the generated website is not very user friendly. In contrast, Sphinx provides a very good way of writing documentation whereas the API overview quality for the C++ domain is not so good.

The guiding idea is as following:

  • Doxygen is run without any supplementary documentation files or pictures

  • Sphinx hosts the RST files, pictures, etc.

  • Sphinx builds with the breathe plugin so it loads at least some of the doxygen information. However, we intend to host both the Doxygen as well as the Sphinx build artefacts.

Hosted output

The docs are build as a CI job to https://anabrid.dev/docs/lucidac-firmware/. This directory holds both the sphinx and doxygen output.

How to build the doxygen locally

Doxygen HTML output

In order to build the doxygen locally,

  1. install doxygen (for instance with your system’s package manager)

  2. run cd docs && make doxygen

  3. point your browser to the generated /docs/doxygen/html/index.html file

Note that Graphviz <https://graphviz.org/> is assumed on the path (dot command). If not available, change the line HAVE_DOT = YES in the Doxyfile to NO. Doxygen then falls back to internally drawn inheritance/collaboration graphs (which are not that beautiful, but still impressive). Build time using dot for the first time is dramatically increased (like 120sec instead of 9sec) but in subsequent builds dramatically decreased (like 1sec instead of 9sec).

We use Doxygen Awesome as a CSS theme to modernize the look at least a bit. It is currently hosed within the firmware repository and has no build-time-dependencies so it will just work.

Doxygen Latex/PDF output

Doxygen also generates latex which “just compiles” with a contemporary standard texlive installation.

Note that doxygen uses a lot of EPS files on intermediate steps internally which require epstopdf and repstopdf` binaries on the path. epspdf is not compatible to these commands. However you can download the epstopdf package from CTAN i.e. the following will work:

cd ~/bin
wget https://mirrors.ctan.org/support/epstopdf.zip
unzip epstopdf.zip
mv epstopdf epstopdf.ctan
ln -s $PWD/epstopdf.ctan/epstopdf.pl  epstopdf
ln -s $PWD/epstopdf.ctan/epstopdf.pl repstopdf

If your path doesn’t include ~/bin yet, add a line such as

PATH="$PATH:$HOME/bin"

to your ~/.bashrc file or similar. Afterwards you should be able to go to the /docs/doxygen/latex output directory and just run make in order to build the file refman.pdf from the input file refman.tex (and it more then 1000 included tex files).

Doxygen: How to add figures

Unfortunately, adding figures requires to manually add them at HTML_EXTRA_FILES, otherwise they won’t be available. This is one of the shortcomings of Doxygen.

How to build the Sphinx locally

  1. Ensure you have the dependencies installed (there should be a file requirements.txt which you can install with pip).

  2. Ensure to run doxygen before sphinx (see above).

  3. Then run something like cd docs/sphinx && make html

  4. Point your browser to docs/sphinx/_build/html/index.html