Building the Documentation

Our documentation is written using:

  • Doxygen to generate API information about the models.

  • reStructuredText as the markup language.

  • Sphinx to convert the documentation into HTML.

  • Breathe to transpile the Doxygen output into a format that Sphinx can use.

Of these dependencies, Doxygen is the only one that isn't included automatically in the CML virtual environment. It will need to be installed on your system.

The Initial Build

Follow our Getting Started Guide to set up a virtual environment, then activate it.

activate ${CML_HOME}/.venv/bin/activate

If you're a CML developer, you can run the CMake dev preset to build all of CML and run unit tests, and then manually build the documentation.

cmake --workflow --preset dev
cmake --build --preset dev -t documentation

If you're simply trying to build only the documentation, you can run the documentation preset instead.

cmake --workflow --preset documentation

Regardless of which preset you choose, the documentation will be placed into the following directory structure:

  • build/docs/doxygen: Generated XML metadata of all CML classes and functions.

  • build/docs/sphinx: The HTML source that can be opened in your browser.

To view the documentation, use your browser of choice to open the index.html file in the Sphinx build directory.

firefox build/docs/sphinx/index.html

Editing the Documentation

When live-editing the documentation, the recommended tool is sphinx-autobuild. sphinx-autobuild is provided by our virtual environment. After generating the documentation, run the livehtml target in our Sphinx makefile, which is a wrapper around sphinx-autobuild with all the necessary options automatically provided.

cd docs/sphinx
make livehtml

This will start a server and watch for changes to any of the reStructuredText files that make up the CML documentation, automatically rebuilding the documentation when you save your changes.

Note

If you edit the CML source code (headers or source files), you'll need to re-run the CMake step above. This is because the XML output needs to be re-generated, which sphinx-autobuild does not do automatically, nor will it automatically detect changes to any of the XML files.

Important

If you create a new .rst file under the docs directory, please be sure to update docs/CMakeLists.txt with the relative path to that file. This allows CMake to determine that it should re-invoke sphinx-build the next time you build CML or the documentation.

See the reStructuredText documentation for examples and references on writing reStructuredText. If you prefer, you may also choose to write documentation in Markdown and convert it to reStructuredText using tools like pandoc.