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
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
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
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.