Tips and Tricks

Here is a small collection of tips and tricks on how to use Sphinx and Hawkmoth for documenting C and C++ code.

Function Parameter Direction

Sphinx does not have a dedicated way of expressing the parameter direction similar to Doxygen @param[dir] command. One approach to emulate this is to define reStructuredText replacement texts, and use them.

For example:

conf.py

rst_prolog = '''
.. |in| replace:: **[in]**
.. |out| replace:: **[out]**
.. |in,out| replace:: **[in,out]**
'''

source code

/**
 * :param foo: |in| Foo parameter.
 */
void bar(char *foo);

By using replacement text, the direction stands out in the source code, you get warnings for typos, and you can modify the appearance across documentation in one place. Instead of **[in]**, you might use ⇒, or whatever you prefer.

Including Source Code Blocks

Doxygen has the @include and @snippet commands to include a source file or a fragment of one into documentation as a block of code.

The Sphinx alternative is literalinclude. The :start-after: and :end-before: options can be used to mimic the block_id of @snippet, but there’s plenty more.

.. literalinclude:: path/to/source.c
   :start-after: Adding a resource
   :end-before: Adding a resource

Using sphinx-autobuild with Hawkmoth

sphinx-autobuild is a handy tool to automatically rebuild Sphinx documentation when you modify the .rst files, with live-reload in the browser.

It’s possible to have it auto rebuild and live-reload source documentation on source code changes by adding --watch <source root> option to sphinx-autobuild, where <source root> matches hawkmoth_root.