Documenting CMake Scripts

Question

I am in a situation where I would like to accurately document many of CMake's custom macros and functions and wondered how to do this.

The first thing that comes to mind is simply to use the built-in syntax and only document scripts, for example:

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

This is normal. However, I would like to use generic doc generators like 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 the appropriate C / C ++ header with the appropriate signatures and documentation directly from the CMake script, which can be processed by doxygen or comparable tools. You can also maintain such a header manually, which is obviously tedious and error prone.

Is there any other way to use the documentation generator with CMake scripts?

Answer 1

Here is the closest I could get. The following has been tested with CMake 2.8.10. CMake 3.0 is under development and will receive a new documentation system based on Sphinx and reStructuredText . I assume this will lead to new ways of documenting your modules.

CMake 2.8 can extract documentation from your modules, but only the documentation at the beginning of the file is considered. All documentation is added as CMake comments, starting with one # . Double ## will be ignored (so you can add comments to your documentation). The end of the documentation is marked with the first line without comment (for example, an empty line)

The first line gives a brief description of the module. It should begin with - and end with a period . or an empty string.

 # - My first documented CMake module. # description 

or # - My first documented module CMake # # description

In HTML, lines starting with two or more spaces (after # ) are formatted with a 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 create documentation for your custom modules only, call

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

The CMAKE_MODULE_PATH allows you to define additional directories to search for modules. Otherwise, your modules should be in the default CMake location. --help-custom-modules restricts documentation to regular, non-CMake-standard modules. If you specify a file name, the documentation will be written to the file, otherwise stdout. If the file name has a recognized extension, the documentation is formatted accordingly.

The following formats are possible:

• .html for HTML documentation
• .1 to .9 for man page
• .docbook for Docbook
• everything else: plain text