[cmake-developers] Properly Documenting a CMake Module

[Gregor Jasny]

Hello,

On 14.02.19 04:39, Timothy Wrona wrote:
> Okay so I dug a little deeper into this and it definitely looks like 
> sphinx is the correct tool to use, but I still have one problem.
> 
> I would like sphinx to be able to extract ".rst" formatted comments 
> directly out of my cmake source files to produce the documentation but I 
> can't seem to figure out how.
> 
> The standard modules that ship with cmake all have this ".rst" section 
> at the top that seems to magically get extracted and turned into online 
> documentation with sphinx, but I just can't figure out how they do it.

The standard modules have a shadow hierarchy at Help/module. For example

https://gitlab.kitware.com/cmake/cmake/blob/master/Help/module/GNUInstallDirs.rst

contains

.. cmake-module:: ../../Modules/GNUInstallDirs.cmake

There's no magic happening.

Thanks,
Gregor