Documenting CMake Modules and other Constructs¶

cetbuildtools2 provides a vendored copy of CMake’s Sphinx extension to parse and generate documentation for CMake modules. Intersphinx is used to cross-reference to the upstream CMake documentation where required. It’s therefore recommended to document modules and their functionality using the domain and style guides outlined in the CMake Developer Guide.

Documenting a Module¶

To integrate a module <module-name> into the cetbuildtools2 documentation, create a new .rst file in documentation/users named <module-name>.rst. The contents of this file only needs to contain the single line:

.. cmake-module:: ../../Modules/<module-name>.cmake

To add this document in the build, simply add it in the documentation/index.rst under the “Using cetbuildtools2” toctree, keeping the entries in alphabetical order. For example, adding a new module bar:

.. toctree::
   :maxdepth: 2
   :hidden:
   :caption: Using cetbuildtools2

   /users/introduction
   /users/alice
   /users/bar
   /users/bob

Simply rebuild and the new module should appear in the generated documentation . Open <build-dir>/documentation/html/index.html in a browser and check that the document appears and is formatted correctly.

Keeping Section Levels Consistent¶

To ensure that the TOC panels remain consistent when browsing through the documentation, use the following characters for marking sections (underlines etc):

-: Title of any document one level below the documentation/ directory
^: Sections of any document one level below the documentation/ directory