diff options
Diffstat (limited to 'Help/manual/cmake-developer.7.rst')
| -rw-r--r-- | Help/manual/cmake-developer.7.rst | 35 |
1 files changed, 18 insertions, 17 deletions
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index eace3a4..f6b8150 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -230,30 +230,31 @@ The ``Modules`` directory contains CMake-language ``.cmake`` module files. Module Documentation -------------------- -To add a module to the CMake documentation, follow these steps: +To document CMake module ``Modules/<module-name>.cmake``, modify +``Help/manual/cmake-modules.7.rst`` to reference the module in the +``toctree`` directive, in sorted order, as:: -1. Add file ``Help/module/<module-name>.rst`` containing just the line:: + /module/<module-name> - .. cmake-module:: ../../Modules/<module-name>.cmake +Then add the module document file ``Help/module/<module-name>.rst`` +containing just the line:: -2. Modify ``Help/manual/cmake-modules.7.rst`` to reference the module in the - toctree directive as:: + .. cmake-module:: ../../Modules/<module-name>.cmake - /module/<module-name> +The ``cmake-module`` directive will scan the module file to extract +reStructuredText markup from comment blocks that start in ``.rst:``. +Add to the top of ``Modules/<module-name>.cmake`` a #-comment of the form: - Keep the toctree in sorted order! - -3. Add to the top of ``Modules/<module-name>.cmake`` a #-comment of the form:: +.. code-block:: cmake - #.rst: - # <module-name> - # ------------- - # - # ...reStructuredText documentation of module... + #.rst: + # <module-name> + # ------------- + # + # <reStructuredText documentation of module> - Comment blocks starting with the line ``#.rst:`` may appear anywhere - in the file. The ``cmake-module`` directive used above will scan the - file to extract reStructuredText markup from such comments. +Additional such ``.rst:`` comments may appear anywhere in the module file. +All such comments must start with ``#`` in the first column. For example, a ``Modules/Findxxx.cmake`` module may contain: |