CMinx Background

This page is meant to provide historical background about documenting CMake modules and the creation of the CMinx project.

The Official Solution

A user, tjwrona1992, asked on StackOverflow how to get their custom CMake module’s documentation to show up using the cmake --help-module command. According to their self answer, they received the following email reply from Brad King (a CMake developer):

There is no way to do this. The only reason --help-module exists at all is
because prior to 3.0 the documentation was generated by the CMake binary
itself, and people were used to the option being available. It is only for
builtin modules and only available for legacy reasons, and may one day go
away in favor of the man pages and html docs.

The online docs, like those at https://cmake.org/cmake/help/v3.14 do publish
a /objects.inv to support intersphinx:

http://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

This was done on request of some users so I haven't looked into how that
works, but one should be able to use sphinx to generate one's own
documentation and still cross-reference CMake's online docs.

If you get that working we'd welcome a MR to add docs describing how,
perhaps in

https://gitlab.kitware.com/cmake/cmake/blob/master/Help/dev/documentation.rst

The question was asked (and answered) in 2019, suggesting that as of 2019 the official way to write documentation for a CMake module was via Sphinx. It should be noted that this solution requires you to write the entirety of the documentation manually (i.e., there is no tool which will extract the signatures of the functions, the variable names, etc.).

Sphinx Domain Solutions

Sphinx domains are a way to package up language-specific directives, and roles.

Sphinx’s (Unofficial) CMake Domain

link

Started (and finished) on 10/21/2013, this is the official (unofficial) CMake domain for Sphinx. The actual domain is pretty bare bones providing:

  • syntax highlighting for code blocks,

  • a directive for documenting a macro, and

  • a directive for documenting a variable

What makes this Sphinx’s official (unofficial) CMake domain is that it is available from the sphinx_contrib organization, which is an organization run by Sphinx for unofficial Sphinx extensions.

As of 10/25/2021 the repo:

  • has no release information,

  • was last committed to on 10/21/2013,

  • has 1 watcher (not the author),

  • 0 stars, and

  • 1 fork

In summary, it feels safe to say that this repo has been abandoned.

scikit-build Modern CMake Domain

link

Started on 10/14/2018 by GitHub user bruxisma, and acquired by scikit-build in August of 20201, this project hosts a mirror of the CMake domain Kitware uses internally.

It contains support for documenting:

  • variables,

  • functions,

  • environment variables, and

  • autodoc style extractor

Of note they also maintain a pypi package which makes it easy to include in your Sphinx setup.

As of 10/25/2021 the repo:

  • is in v3.19,

  • was last committed to on 8/15/2021,

  • has 1 watcher (the author),

  • 9 stars, and

  • 3 forks

MarcoKoch CMake Domain

link

Started on 7/7/2020, and developed seemingly independent of scikit-build’s CMake domain. Supports:

  • variables,

  • macros,

  • functions,

  • modules, and

  • targets

As of 10/25/2021 the repo:

  • is in a beta state,

  • was last committed to on 9/6/2020,

  • has 1 watcher (the author),

  • 0 stars, and

  • 0 forks

In summary this project also seems to be abandoned, but given that it’s being run by a solo developer, it’s also possible that it’s on the back-burner for the moment.

CMinx

Started 8/26/2019. CMinx is envisioned as a Doxygen-like solution to documenting CMake modules. This means that CMinx is run on your source directory and in return generates the reST files for you.