[CMake] Syntax to document cmake files, functions and macros

[Marc Herbert]

> 
> On 24 Dec 2018, at 03:32, Oleksii Vilchanskyi <oleksii.vilchanskyi at gmail.com> wrote:
> 
> On 12/24/18 12:01 PM, Olivier Croquette wrote:
>> I have quite a few .cmake files that I want to document. They define
>> functions, macros, and variables, and I was wondering if there is any
>> standard or tooling to help.
> 
> Yes, see [1]. You can find concrete examples at [2].
> 
> [1]:
> <https://cmake.org/cmake/help/latest/manual/cmake-developer.7.html#help>
> [2]: <https://gitlab.kitware.com/cmake/cmake/tree/master/Modules>

This is very promising, however:

https://cmake.org/cmake/help/latest/manual/cmake-developer.7.html#module-documentation

“ This manual is intended for reference by developers modifying the CMake source tree itself,
and by those authoring externally-maintained modules.
...
To document CMake module Modules/<module-name>.cmake,
modify Help/manual/cmake-modules.7.rst to reference the module in the toctree directive
...
Test the documentation formatting by running cmake --help-module <module-name>,
and also by enabling the SPHINX_HTML and SPHINX_MAN options to build the documentation."


So is there a relatively simple way to run the same tooling on any regular, non-module .cmake files
too and produce project-specific documentation?