.. Copyright 2021 CMakePP
..
.. Licensed under the Apache License, Version 2.0 (the "License");
.. you may not use this file except in compliance with the License.
.. You may obtain a copy of the License at
..
.. http://www.apache.org/licenses/LICENSE-2.0
..
.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS,
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.. See the License for the specific language governing permissions and
.. limitations under the License.
..
********************
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
   :code:`include_guard()` call or any other commands. Failing
   this requirement will result in a parse error.
#. The module doccomment must have the :code:`@module` directive
   in the same line as the opening :code:`#[[[` tag. This requirement
   ensures a module doccomment is not accidentally attached to
   a command instead.
#. The :code:`@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:

.. literalinclude:: ../../../tests/test_samples/basic_module.cmake
   :language: cmake

This doccomment is translated by CMinx to the following RST:

.. literalinclude:: ../../../tests/test_samples/corr_rst/basic_module.rst
   :language: rst

As one can see, the :code:`.. 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:

.. literalinclude:: ../../../tests/test_samples/advanced_module.cmake
   :language: cmake

CMinx generates the following RST from this source file:

.. literalinclude:: ../../../tests/test_samples/corr_rst/advanced_module.rst
   :language: rst

Here, one can see that the module name and the title were overridden with
the name set in the :code:`@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 :code:`@module` directive.

.. note::
   The above is an intentionally obtuse usage of doccomments
   to show how the :code:`@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.