Documentation¶

Maud builds include a target named documentation. Building this target globs up all reStructuredText (.rst) files and renders them with Sphinx.

$ ninja -C .build documentation
[73/76] Building dirhtml with sphinx

# output from each builder is in .build/documentation/$builder
$ python -m http.server -d .build/documentation/dirhtml 8000
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...

$ xdg-open http://localhost:8000

By default only dirhtml will be built. option(SPHINX_BUILDERS) controls which builder are used or disables building documentation if no builders are specified.

All dependencies necessary for building documentation are installed to a virtual environment located in .build/documentation/venv. The versions of all dependencies are frozen. This ensures isolation from other Python environments and improves repeatability of builds. If a Python3 interpreter is not discovered, then documentation will be disabled.

The documentation root directory is the project’s root directory. Write documentation throughout your project, directly alongside the code it explains. (If nothing else it makes inclusion directives easier.) If you need docs in their own dir or you need generated docs, set(MAUD_DOCUMENTATION_DIR) in cmake… but first try writing a sphinx extension.

Configuration¶

If explicit configuration becomes necessary for your project, create a directory named sphinx_configuration/ at the root of your documentation sources. This directory will be passed to Sphinx as –conf-dir so it should contain your conf.py. The default configuration is provided as a module, so if you only need to make a small tweak (for example adding an extension), you can just write

from maud.default_sphinx_configuration import *
extensions += ["my_local_ext"]

(The default conf.py is just from maud.default_sphinx_configuration import *)

If the file sphinx_configuration/requirements.txt exists, then it will be used to install dependencies to Sphinx’ virtual environment. The default configuration includes sphinx and the following extensions:

Furo	my favorite Sphinx theme
Trike	extracts APIdoc for easy inclusion
sphinx_inline_tabs	adds `.. tab::` for writing inline tabbed content
sphinx_copybutton	adds a little “copy” button to the right of your code blocks
ifconfig	conditionally includes content based on configuration values

Maud also injects itself as a sphinx extension and sets some configuration when the values are obvious or can be inferred:

the Sphinx project name will be the same as the CMake PROJECT_NAME
The identity and URL of your forge will be inferred and used to set up Furo’s buttons
Author and copyright will be guessed from the first commit to the Sphinx root document

this extension also provides conf.py access to the cmake CACHE, which includes build Options. For example, option(ENABLE_DIAGRAMS) might be used in conf.py to conditionally enable an extension:

from maud import CACHE
if CACHE["ENABLE_DIAGRAMS"]:
    extensions += ['awesome-diagrams-ext']

… or option(DOCUMENT_EXPERIMENTAL) might be used with ifconfig:

.. ifconfig:: CACHE["DOCUMENT_EXPERIMENTAL"]

  .. experimental features doc

Note

This last example does not require explicit conf.py