What is the proper way to document a CMake module?

Question

A quick Google search (...actually many rather extensive Google searches) have not been able to explain how to properly document a CMake module.

What I'm looking for is a way to document custom CMake modules so that they work with the cmake --help-module <module_name> command. Is there any standard way of doing this? Can anyone point me to some good examples? The documentation process seems oddly.... not well documented. Haha.

How are modules that work with cmake --help-module documented?

Any help is appreciated.

Answer 1

Quote from an email response I got from Brad King (member of the CMake Developers email list):

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

It sounds like using Sphinx is the way to go.

Additional info:

How does Sphinx know to go parse that ".cmake" file? Does Sphinx recognize the "cmake-module" keyword in a special way and know what to do with it?

it’s from a Sphinx module that you can find the in the CMake sources Utilities/Sphinx/cmake.py. Or you can install this file using pip:

pip install sphinxcontrib-moderncmakedomain

When configuring Sphinx, you have to name the extensions to use in Sphinx's configuration file (conf.py) and add the name of the extension (sphinxcontrib.moderncmakedomain) to the extensions array.