[cmake-developers] Properly Documenting a CMake Module

[Brad King]

On 2/12/19 6:37 PM, Timothy Wrona wrote:
> a way to document custom CMake modules so that they work with the
> "cmake --help-module <module_name>" command

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

-Brad