[Cmake-commits] CMake branch, master, updated. v3.13.0-493-gec43aca
Kitware Robot
kwrobot at kitware.com
Tue Nov 20 16:53:05 EST 2018
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "CMake".
The branch, master has been updated
via ec43aca7037987e189a39ebe2c93c7b4e219a9a7 (commit)
via 8369e3e7822712f9415440aede2a470a50925107 (commit)
via 664d6178d82edd74e184ff31c8a1faa01b884a48 (commit)
from ea52ec9420a6f147a78276bda8110999faa9e094 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=ec43aca7037987e189a39ebe2c93c7b4e219a9a7
commit ec43aca7037987e189a39ebe2c93c7b4e219a9a7
Merge: ea52ec9 8369e3e
Author: Craig Scott <craig.scott at crascit.com>
AuthorDate: Tue Nov 20 21:48:27 2018 +0000
Commit: Kitware Robot <kwrobot at kitware.com>
CommitDate: Tue Nov 20 16:48:45 2018 -0500
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 <kwrobot at kitware.com>
Merge-request: !2621
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=8369e3e7822712f9415440aede2a470a50925107
commit 8369e3e7822712f9415440aede2a470a50925107
Author: Brad King <brad.king at kitware.com>
AuthorDate: Thu Nov 15 13:43:09 2018 -0500
Commit: Craig Scott <craig.scott at crascit.com>
CommitDate: Tue Nov 20 21:03:01 2018 +1100
Help/dev: Modernize module example in the CMake Documentation Guide
diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst
index 1b2c942..c302790 100644
--- a/Help/dev/documentation.rst
+++ b/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
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=664d6178d82edd74e184ff31c8a1faa01b884a48
commit 664d6178d82edd74e184ff31c8a1faa01b884a48
Author: Brad King <brad.king at kitware.com>
AuthorDate: Thu Nov 15 13:38:57 2018 -0500
Commit: Craig Scott <craig.scott at crascit.com>
CommitDate: Tue Nov 20 21:03:01 2018 +1100
Help: Modernize example find module docs in cmake-developer(7)
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index b949464..85ed935 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/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.
-----------------------------------------------------------------------
Summary of changes:
Help/dev/documentation.rst | 84 ++++++++++++++++-------------------
Help/manual/cmake-developer.7.rst | 93 +++++++++++++++++++++++++--------------
2 files changed, 99 insertions(+), 78 deletions(-)
hooks/post-receive
--
CMake
More information about the Cmake-commits
mailing list