Merge topic 'doc-module-doc-syntax'

8369e3e782 Help/dev: Modernize module example in the CMake Documentation Guide
664d6178d8 Help: Modernize example find module docs in cmake-developer(7)

Acked-by: Kitware Robot <[email protected]>
Merge-request: !2621

Help/dev/documentation.rst

@@ -458,32 +458,22 @@ reStructuredText markup from comment blocks that start in ``.rst:``.
 At the top of ``Modules/<module-name>.cmake``, begin with the following
 license notice:
 
-.. code-block:: cmake
+::
 
  # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
  # file Copyright.txt or https://cmake.org/licensing for details.
 
 After this notice, add a *BLANK* line.  Then, add documentation using
-a `Line Comment`_ block of the form:
-
-.. code-block:: cmake
-
- #.rst:
- # <module-name>
- # -------------
- #
- # <reStructuredText documentation of module>
-
-or a `Bracket Comment`_ of the form:
+a `Bracket Comment`_ of the form:
 
 ::
 
- #[[.rst:
- <module-name>
- -------------
+  #[=======================================================================[.rst:
+  <module-name>
+  -------------
 
- <reStructuredText documentation of module>
- #]]
+  <reStructuredText documentation of module>
+  #]=======================================================================]
 
 Any number of ``=`` may be used in the opening and closing brackets
 as long as they match.  Content on the line containing the closing
@@ -496,35 +486,38 @@ For example, a ``Findxxx.cmake`` module may contain:
 
 ::
 
- # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
- # file Copyright.txt or https://cmake.org/licensing for details.
+  # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+  # file Copyright.txt or https://cmake.org/licensing for details.
+
+  #[=======================================================================[.rst:
+  FindXxx
+  -------
+
+  This is a cool module.
+  This module does really cool stuff.
+  It can do even more than you think.
+
+  It even needs two paragraphs to tell you about it.
+  And it defines the following variables:
+
+  ``VAR_COOL``
+    this is great isn't it?
+  ``VAR_REALLY_COOL``
+    cool right?
+  #]=======================================================================]
+
+  <code>
+
+  #[=======================================================================[.rst:
+  .. command:: xxx_do_something
+
+   This command does something for Xxx::
 
- #.rst:
- # FindXxx
- # -------
- #
- # This is a cool module.
- # This module does really cool stuff.
- # It can do even more than you think.
- #
- # It even needs two paragraphs to tell you about it.
- # And it defines the following variables:
- #
- # * VAR_COOL: this is great isn't it?
- # * VAR_REALLY_COOL: cool right?
-
- <code>
-
- #[========================================[.rst:
- .. command:: xxx_do_something
-
-  This command does something for Xxx::
-
-   xxx_do_something(some arguments)
- #]========================================]
- macro(xxx_do_something)
-   <code>
- endmacro()
+    xxx_do_something(some arguments)
+  #]=======================================================================]
+  macro(xxx_do_something)
+    <code>
+  endmacro()
 
 Test the documentation formatting by running
 ``cmake --help-module <module-name>``, and also by enabling the
@@ -534,5 +527,4 @@ have a .cmake file in this directory NOT show up in the modules
 documentation, simply leave out the ``Help/module/<module-name>.rst``
 file and the ``Help/manual/cmake-modules.7.rst`` toctree entry.
 
-.. _`Line Comment`: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#line-comment
 .. _`Bracket Comment`: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#bracket-comment

Help/manual/cmake-developer.7.rst

@@ -196,49 +196,78 @@ them.
 A Sample Find Module
 --------------------
 
-We will describe how to create a simple find module for a library
-``Foo``.
+We will describe how to create a simple find module for a library ``Foo``.
 
-The first thing that is needed is a license notice.
+The top of the module should begin with a license notice, followed by
+a blank line, and then followed by a :ref:`Bracket Comment`.  The comment
+should begin with ``.rst:`` to indicate that the rest of its content is
+reStructuredText-format documentation.  For example:
 
-.. code-block:: cmake
+::
 
- # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
- # file Copyright.txt or https://cmake.org/licensing for details.
+  # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+  # file Copyright.txt or https://cmake.org/licensing for details.
 
-Next we need module documentation.  CMake's documentation system requires you
-to follow the license notice with a blank line and then with a documentation
-marker and the name of the module.  You should follow this with a simple
-statement of what the module does.
+  #[=======================================================================[.rst:
+  FindFoo
+  -------
 
-.. code-block:: cmake
+  Finds the Foo library.
 
-  #.rst:
-  # FindFoo
-  # -------
-  #
-  # Finds the Foo library
-  #
+  Imported Targets
+  ^^^^^^^^^^^^^^^^
 
-More description may be required for some packages.  If there are
-caveats or other details users of the module should be aware of, you can
-add further paragraphs below this.  Then you need to document what
-variables and imported targets are set by the module, such as
+  This module provides the following imported targets, if found:
 
-.. code-block:: cmake
+  ``Foo::Foo``
+    The Foo library
+
+  Result Variables
+  ^^^^^^^^^^^^^^^^
+
+  This will define the following variables:
+
+  ``Foo_FOUND``
+    True if the system has the Foo library.
+  ``Foo_VERSION``
+    The version of the Foo library which was found.
+  ``Foo_INCLUDE_DIRS``
+    Include directories needed to use Foo.
+  ``Foo_LIBRARIES``
+    Libraries needed to link to Foo.
+
+  Cache Variables
+  ^^^^^^^^^^^^^^^
+
+  The following cache variables may also be set:
+
+  ``Foo_INCLUDE_DIR``
+    The directory containing ``foo.h``.
+  ``Foo_LIBRARY``
+    The path to the Foo library.
+
+  #]=======================================================================]
+
+The module documentation consists of:
+
+* An underlined heading specifying the module name.
+
+* A simple description of what the module finds.
+  More description may be required for some packages.  If there are
+  caveats or other details users of the module should be aware of,
+  specify them here.
+
+* A section listing imported targets provided by the module, if any.
+
+* A section listing result variables provided by the module.
 
-  # This will define the following variables::
-  #
-  #   Foo_FOUND    - True if the system has the Foo library
-  #   Foo_VERSION  - The version of the Foo library which was found
-  #
-  # and the following imported targets::
-  #
-  #   Foo::Foo   - The Foo library
+* Optionally a section listing cache variables used by the module, if any.
 
-If the package provides any macros, they should be listed here, but can
-be documented where they are defined.
+If the package provides any macros or functions, they should be listed in
+an additional section, but can be documented by additional ``.rst:``
+comment blocks immediately above where those macros or functions are defined.
 
+The find module implementation may begin below the documentation block.
 Now the actual libraries and so on have to be found.  The code here will
 obviously vary from module to module (dealing with that, after all, is the
 point of find modules), but there tends to be a common pattern for libraries.