Documenting a Module

Note

The generated module documentation will only be processed by Sphinx in versions greater than or equal to 5.2. In older versions, the documentation body text will simply be ignored. The optional module name will still be processed if supplied.

CMinx is able to generate documentation for a CMake module in much the same way that functions and other elements are documented. There are a few differences however:

The module doccomment must be the first non-comment element of the file. This means it must occur before the usual include_guard() call or any other commands. Failing this requirement will result in a parse error.
The module doccomment must have the @module directive in the same line as the opening #[[[ tag. This requirement ensures a module doccomment is not accidentally attached to a command instead.
The @module directive may have a single optional argument that specifies a module name to be used instead of the autogenerated name. Setting the module name will also set the generated documentation’s title to the given name. The file name will be unchanged.

A basic module doccomment looks like so:

#[[[ @module
# This is a basic CMake module.
# The :code:`@module` component is required and
# must appear on the first line. An
# optional module name may appear after the
# module tag, if it is not present the module
# name is autogenerated as usual. This
# file allows the module name to be autogenerated.
#]]

This doccomment is translated by CMinx to the following RST:

#########################
test_samples.basic_module
#########################

.. module:: test_samples.basic_module

   This is a basic CMake module.
   The :code:`@module` component is required and
   must appear on the first line. An
   optional module name may appear after the
   module tag, if it is not present the module
   name is autogenerated as usual. This
   file allows the module name to be autogenerated.
   

As one can see, the .. module:: directive still has a module name even though the source does not specify one. This is because CMinx autogenerates a module name based on the source filename and its path relative to the input path that CMinx is given on the command line. The module name generation can be adjusted through the configuration file.

A module doccomment that overrides the autogenerated module name can be seen here:

#[[[ @module advanced_module_name
# This is a more advanced usage of a module
# doc comment. A call to `function()` immediately
# follows this comment but because of the `@module` directive
# this comment is not considered a doccomment on the `function()`
# call. This file also sets the module name to `advanced_module_name`
# instead of allowing it to be autogenerated.
#]]
function(test_func param1)

endfunction()

CMinx generates the following RST from this source file:

####################
advanced_module_name
####################

.. module:: advanced_module_name

   This is a more advanced usage of a module
   doc comment. A call to `function()` immediately
   follows this comment but because of the `@module` directive
   this comment is not considered a doccomment on the `function()`
   call. This file also sets the module name to `advanced_module_name`
   instead of allowing it to be autogenerated.
   


.. function:: test_func(param1)

   

Here, one can see that the module name and the title were overridden with the name set in the @module directive. One may also see that although the doccomment appears directly above a function declaration, it is not interpreted as a function doccomment due to the @module directive.

Note

The above is an intentionally obtuse usage of doccomments to show how the @module directive affects parsing. It is heavily advised to separate the module doccomment and any subsequent code without doccomments by at least a blank line. Preferably, documented code should be placed after the module doccomment to help visually separate the module doccomment from any command.