Docs

☑️ Requirements

Documentation (like this web-page you’re reading now 😃) is created using a combination of three core tools:

  • Doxygen

    A powerful tool for automatically generating API documentation for several languages. In this project we use it to generate XML from C/C++ code that is fed into the other tools.

  • Sphinx

    A Python tool for generating documentation from Python files and reStructuredText (reST/.rst) files. The reST files allow for manual documentation and further customisation of the layout.

  • Breathe

    A Python package for bridging Doxygen and Sphinx, so that we can use Sphinx to generate documentation for C/C++ code.

The build system will create a Python virtual environment and install the necessary Python packages (see doc/requirements.txt), however you must install Doxygen and Python for this to work.

Note

If you’d rather not build the documentation then configure your build with -DBUILD_DOCS=OFF to disable the generation of the documentation.

📜 Building Documentation

To build the documentation cmake must be configured with -DBUILD_DOCS.

The build system supports generating multiple output types of documentation. The DOCS_OUT_TYPES cmake option takes a list of formats to build. For example:

$ cmake -GNinja -DBUILD_DOCS=ON -DDOCS_OUT_TYPES='html;man' ..
$ ninja -j16 docs

will build HTML and man-pages documentation. For a full list of supported formats please see the name tags of the Sphinx builders. You can also build each documentation type individually using the corresponding docs_<type> target.

Note

Some output types, such as applehelp may require extra configuration in the doc/conf.py file.

✍️ Writing documentation

To write documentation for your project using this system you need to write reStructuredText files. The Sphinx projects hosts a nice introduction to reST.

To reference code documentation you can use breathe directives which are documented here and you may find it useful to take a look at some of the .rst files already in this project.

And finally to document the C code itself you can use Doxygen comments and the Doxygen special commands that Doxygen supports.

Note

For Doxygen to parse a file it must have a doxygen comment like:

/// \file
/// Your file-level documentation here.

at the top. Without the \file directive Doxygen will ignore your file. The name of the file can be left blank so that Doxygen uses the file name.

In addition to Doxygen special commands you can also embed reStructuredText into code comments using the \rst, \rst_block and \rst_end commands. For example to embed a sphinx role inline you can do:

/// Example description...
///
/// Remember to call \rst :cppref:`~c/memory/free` \rst_end.

Or to embed a block of rst you can do:

/// Example description...
///
/// \rst
///
/// .. code-block:: c
///
///       int x = 0;
///
/// \rst_end

Warning

Sadly, it is not currently possible to link to external websites using Doxygen tagfiles because breathe doesn’t support this. See: https://github.com/michaeljones/breathe/issues/328.

In addition to the standard Sphinx roles this project adds three custom roles:

Prefixing the contents with a ~ character will shorten the generated url text to just the final piece of the url or in the case of the :man7: role just the <page>. For example:

Warning

Sphinx’s :manpage: role is currently broken; it doesn’t create urls correctly and instead will always link to the value of manpage_url, hence the need for the :man7: role.