Documenting CMake scripts

I find myself in a situation where I would like to accurately document a host of custom CMake macros and functions and was wondering how to do it.

The first thing that comes to mind is simply using the built-in syntax and only document scripts, like so:

# -----------------------------
# [FUNCTION_NAME | MACRO_NAME]
# -----------------------------
# ... description ...
# -----------------------------

This is fine. However, I'd like to employ common doc generators, for instance doxygen, to also generate external documentation that can be read by anyone without looking at the implementation (which is a common scenario).

One way would be to write a simple parser that generates a corresponding C/C++ header with the appropriate signatures and documentation directly from the CMake script, which could the be processed by doxygen or comparable tools. One could also maintain such a header by hand - which is obviously tedious and error prone.

Is there any other way to employ a documentation generator with CMake scripts?

Here is the closest I could get. The following was tested with CMake 2.8.10. Currently, CMake 3.0 is under development which will get a new documentation system based on Sphinx and reStructuredText. I guess that this will bring new ways to document your modules.

CMake 2.8 can extract documentation from your modules, but only documentation at the beginning of the file is considered. All documentation is added as CMake comments, beginning with a single #. Double ## will be ignored (so you can add comments to your documentation). The end of documentation is marked by the first non-comment line (e.g. an empty line)

The first line gives a brief description of the module. It must start with - and end with a period . or a blank line.

# - My first documented CMake module.
# description

or # - My first documented CMake module # # description

In HTML, lines starting with at two or more spaces (after the #) are formatted with monospace font.

Example:

# - My custom macros to do foo
#
# This module provides the macro foo().
# These macros serve to demonstrate the documentation capabilietes of CMake. 
#    
#    FOO( [FILENAME <file>]
#         [APPEND]
#         [VAR <variable_name>]
#    )
#
# The FOO() macro can be used to do foo or bar. If FILENAME is given, 
# it even writes baz. 

MACRO( FOO )
 ...
ENDMACRO()

To generate documentation for your custom modules only, call

cmake -DCMAKE_MODULE_PATH:STRING=. --help-custom-modules test.html

Setting CMAKE_MODULE_PATH allows you to define additional directories to search for modules. Otherwise, your modules need to be in the default CMake location. --help-custom-modules limits the documentation generation to custom, non-CMake-standar modules. If you give a filename, the documentation is written to the file, to stdout otherwise. If the filename has a recognized extension, the documentation is formatted accordingly.

The following formats are possible: