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.
cmake --help-module <module_name>, only cmake built-in modules can be. As for documentation, I'd look the the CMake source and copy the rough format for how to write the reStructuredText documentation. – Hittite