FeatureSummary: Format documentation

Revise the documentation using reStructuredText inline markup and
explicit blocks so that it formats well.

Modules/FeatureSummary.cmake

@@ -2,19 +2,10 @@
 FeatureSummary
 --------------
 
-Macros for generating a summary of enabled/disabled features
+Functions for generating a summary of enabled/disabled features.
 
-
-
-This module provides the macros feature_summary(),
-set_package_properties() and add_feature_info().  For compatibility it
-also still provides set_package_info(), set_feature_info(),
-print_enabled_features() and print_disabled_features().
-
-These macros can be used to generate a summary of enabled and disabled
-packages and/or feature for a build tree:
-
-::
+These functions can be used to generate a summary of enabled and disabled
+packages and/or feature for a build tree such as::
 
     -- The following OPTIONAL packages have been found:
     LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
@@ -27,242 +18,9 @@ packages and/or feature for a build tree:
        * Enables macros in MyWordProcessor
     Foo , Foo provides cool stuff.
 
+Functions
+^^^^^^^^^
 
-
-
-
-::
-
-    FEATURE_SUMMARY( [FILENAME <file>]
-                     [APPEND]
-                     [VAR <variable_name>]
-                     [INCLUDE_QUIET_PACKAGES]
-                     [FATAL_ON_MISSING_REQUIRED_PACKAGES]
-                     [DESCRIPTION "Found packages:"]
-                     WHAT (ALL | PACKAGES_FOUND | PACKAGES_NOT_FOUND
-                          | ENABLED_FEATURES | DISABLED_FEATURES)
-                   )
-
-
-
-The FEATURE_SUMMARY() macro can be used to print information about
-enabled or disabled packages or features of a project.  By default,
-only the names of the features/packages will be printed and their
-required version when one was specified.  Use SET_PACKAGE_PROPERTIES()
-to add more useful information, like e.g.  a download URL for the
-respective package or their purpose in the project.
-
-The WHAT option is the only mandatory option.  Here you specify what
-information will be printed:
-
-``ALL``
- print everything
-``ENABLED_FEATURES``
- the list of all features which are enabled
-``DISABLED_FEATURES``
- the list of all features which are disabled
-``PACKAGES_FOUND``
- the list of all packages which have been found
-``PACKAGES_NOT_FOUND``
- the list of all packages which have not been found
-``OPTIONAL_PACKAGES_FOUND``
- only those packages which have been found which have the type OPTIONAL
-``OPTIONAL_PACKAGES_NOT_FOUND``
- only those packages which have not been found which have the type OPTIONAL
-``RECOMMENDED_PACKAGES_FOUND``
- only those packages which have been found which have the type RECOMMENDED
-``RECOMMENDED_PACKAGES_NOT_FOUND``
- only those packages which have not been found which have the type RECOMMENDED
-``REQUIRED_PACKAGES_FOUND``
- only those packages which have been found which have the type REQUIRED
-``REQUIRED_PACKAGES_NOT_FOUND``
- only those packages which have not been found which have the type REQUIRED
-``RUNTIME_PACKAGES_FOUND``
- only those packages which have been found which have the type RUNTIME
-``RUNTIME_PACKAGES_NOT_FOUND``
- only those packages which have not been found which have the type RUNTIME
-
-With the exception of the ``ALL`` value, these values can be combined
-in order to customize the output. For example:
-
-::
-
-   feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
-
-
-
-If a FILENAME is given, the information is printed into this file.  If
-APPEND is used, it is appended to this file, otherwise the file is
-overwritten if it already existed.  If the VAR option is used, the
-information is "printed" into the specified variable.  If FILENAME is
-not used, the information is printed to the terminal.  Using the
-DESCRIPTION option a description or headline can be set which will be
-printed above the actual content.  If INCLUDE_QUIET_PACKAGES is given,
-packages which have been searched with find_package(...  QUIET) will
-also be listed.  By default they are skipped.  If
-FATAL_ON_MISSING_REQUIRED_PACKAGES is given, CMake will abort if a
-package which is marked as REQUIRED has not been found.
-
-Example 1, append everything to a file:
-
-::
-
-   feature_summary(WHAT ALL
-                   FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
-
-
-
-Example 2, print the enabled features into the variable
-enabledFeaturesText, including QUIET packages:
-
-::
-
-   feature_summary(WHAT ENABLED_FEATURES
-                   INCLUDE_QUIET_PACKAGES
-                   DESCRIPTION "Enabled Features:"
-                   VAR enabledFeaturesText)
-   message(STATUS "${enabledFeaturesText}")
-
-
-
-
-
-::
-
-    SET_PACKAGE_PROPERTIES(<name> PROPERTIES
-                           [ URL <url> ]
-                           [ DESCRIPTION <description> ]
-                           [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
-                           [ PURPOSE <purpose> ]
-                          )
-
-
-
-Use this macro to set up information about the named package, which
-can then be displayed via FEATURE_SUMMARY().  This can be done either
-directly in the Find-module or in the project which uses the module
-after the find_package() call.  The features for which information can
-be set are added automatically by the find_package() command.
-
-URL: this should be the homepage of the package, or something similar.
-Ideally this is set already directly in the Find-module.
-
-DESCRIPTION: A short description what that package is, at most one
-sentence.  Ideally this is set already directly in the Find-module.
-
-TYPE: What type of dependency has the using project on that package.
-Default is OPTIONAL.  In this case it is a package which can be used
-by the project when available at buildtime, but it also work without.
-RECOMMENDED is similar to OPTIONAL, i.e.  the project will build if
-the package is not present, but the functionality of the resulting
-binaries will be severly limited.  If a REQUIRED package is not
-available at buildtime, the project may not even build.  This can be
-combined with the FATAL_ON_MISSING_REQUIRED_PACKAGES argument for
-feature_summary().  Last, a RUNTIME package is a package which is
-actually not used at all during the build, but which is required for
-actually running the resulting binaries.  So if such a package is
-missing, the project can still be built, but it may not work later on.
-If set_package_properties() is called multiple times for the same
-package with different TYPEs, the TYPE is only changed to higher TYPEs
-( RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED ), lower TYPEs are
-ignored.  The TYPE property is project-specific, so it cannot be set
-by the Find-module, but must be set in the project.
-
-PURPOSE: This describes which features this package enables in the
-project, i.e.  it tells the user what functionality he gets in the
-resulting binaries.  If set_package_properties() is called multiple
-times for a package, all PURPOSE properties are appended to a list of
-purposes of the package in the project.  As the TYPE property, also
-the PURPOSE property is project-specific, so it cannot be set by the
-Find-module, but must be set in the project.
-
-
-
-Example for setting the info for a package:
-
-::
-
-   find_package(LibXml2)
-   set_package_properties(LibXml2 PROPERTIES
-                          DESCRIPTION "A XML processing library."
-                          URL "http://xmlsoft.org/")
-
-
-
-::
-
-   set_package_properties(LibXml2 PROPERTIES
-                          TYPE RECOMMENDED
-                          PURPOSE "Enables HTML-import in MyWordProcessor")
-   ...
-   set_package_properties(LibXml2 PROPERTIES
-                          TYPE OPTIONAL
-                          PURPOSE "Enables odt-export in MyWordProcessor")
-
-
-
-::
-
-   find_package(DBUS)
-   set_package_properties(DBUS PROPERTIES
-     TYPE RUNTIME
-     PURPOSE "Necessary to disable the screensaver during a presentation" )
-
-
-
-::
-
-    ADD_FEATURE_INFO(<name> <enabled> <description>)
-
-Use this macro to add information about a feature with the given
-<name>.  <enabled> contains whether this feature is enabled or not,
-<description> is a text describing the feature.  The information can
-be displayed using feature_summary() for ENABLED_FEATURES and
-DISABLED_FEATURES respectively.
-
-Example for setting the info for a feature:
-
-::
-
-   option(WITH_FOO "Help for foo" ON)
-   add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
-
-
-
-
-
-The following macros are provided for compatibility with previous
-CMake versions:
-
-::
-
-    SET_PACKAGE_INFO(<name> <description> [<url> [<purpose>] ] )
-
-Use this macro to set up information about the named package, which
-can then be displayed via FEATURE_SUMMARY().  This can be done either
-directly in the Find-module or in the project which uses the module
-after the find_package() call.  The features for which information can
-be set are added automatically by the find_package() command.
-
-::
-
-    PRINT_ENABLED_FEATURES()
-
-Does the same as FEATURE_SUMMARY(WHAT ENABLED_FEATURES DESCRIPTION
-"Enabled features:")
-
-::
-
-    PRINT_DISABLED_FEATURES()
-
-Does the same as FEATURE_SUMMARY(WHAT DISABLED_FEATURES DESCRIPTION
-"Disabled features:")
-
-::
-
-    SET_FEATURE_INFO(<name> <description> [<url>] )
-
-Does the same as SET_PACKAGE_INFO(<name> <description> <url> )
 #]=======================================================================]
 
 #=============================================================================
@@ -363,6 +121,95 @@ function(_FS_GET_FEATURE_SUMMARY _property _var _includeQuiet)
 endfunction()
 
 
+#[=======================================================================[.rst:
+.. command:: feature_summary
+
+  ::
+
+    feature_summary( [FILENAME <file>]
+                     [APPEND]
+                     [VAR <variable_name>]
+                     [INCLUDE_QUIET_PACKAGES]
+                     [FATAL_ON_MISSING_REQUIRED_PACKAGES]
+                     [DESCRIPTION "Found packages:"]
+                     WHAT (ALL | PACKAGES_FOUND | PACKAGES_NOT_FOUND
+                          | ENABLED_FEATURES | DISABLED_FEATURES)
+                   )
+
+  The ``feature_summary()`` macro can be used to print information about
+  enabled or disabled packages or features of a project.  By default,
+  only the names of the features/packages will be printed and their
+  required version when one was specified.  Use ``set_package_properties()``
+  to add more useful information, like e.g.  a download URL for the
+  respective package or their purpose in the project.
+
+  The ``WHAT`` option is the only mandatory option.  Here you specify what
+  information will be printed:
+
+  ``ALL``
+   print everything
+  ``ENABLED_FEATURES``
+   the list of all features which are enabled
+  ``DISABLED_FEATURES``
+   the list of all features which are disabled
+  ``PACKAGES_FOUND``
+   the list of all packages which have been found
+  ``PACKAGES_NOT_FOUND``
+   the list of all packages which have not been found
+  ``OPTIONAL_PACKAGES_FOUND``
+   only those packages which have been found which have the type OPTIONAL
+  ``OPTIONAL_PACKAGES_NOT_FOUND``
+   only those packages which have not been found which have the type OPTIONAL
+  ``RECOMMENDED_PACKAGES_FOUND``
+   only those packages which have been found which have the type RECOMMENDED
+  ``RECOMMENDED_PACKAGES_NOT_FOUND``
+   only those packages which have not been found which have the type RECOMMENDED
+  ``REQUIRED_PACKAGES_FOUND``
+   only those packages which have been found which have the type REQUIRED
+  ``REQUIRED_PACKAGES_NOT_FOUND``
+   only those packages which have not been found which have the type REQUIRED
+  ``RUNTIME_PACKAGES_FOUND``
+   only those packages which have been found which have the type RUNTIME
+  ``RUNTIME_PACKAGES_NOT_FOUND``
+   only those packages which have not been found which have the type RUNTIME
+
+  With the exception of the ``ALL`` value, these values can be combined
+  in order to customize the output. For example:
+
+  .. code-block:: cmake
+
+    feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
+
+  If a ``FILENAME`` is given, the information is printed into this file.  If
+  ``APPEND`` is used, it is appended to this file, otherwise the file is
+  overwritten if it already existed.  If the VAR option is used, the
+  information is "printed" into the specified variable.  If ``FILENAME`` is
+  not used, the information is printed to the terminal.  Using the
+  ``DESCRIPTION`` option a description or headline can be set which will be
+  printed above the actual content.  If ``INCLUDE_QUIET_PACKAGES`` is given,
+  packages which have been searched with ``find_package(... QUIET)`` will
+  also be listed.  By default they are skipped.  If
+  ``FATAL_ON_MISSING_REQUIRED_PACKAGES`` is given, CMake will abort if a
+  package which is marked as ``REQUIRED`` has not been found.
+
+  Example 1, append everything to a file:
+
+  .. code-block:: cmake
+
+   feature_summary(WHAT ALL
+                   FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
+
+  Example 2, print the enabled features into the variable
+  enabledFeaturesText, including QUIET packages:
+
+  .. code-block:: cmake
+
+   feature_summary(WHAT ENABLED_FEATURES
+                   INCLUDE_QUIET_PACKAGES
+                   DESCRIPTION "Enabled Features:"
+                   VAR enabledFeaturesText)
+   message(STATUS "${enabledFeaturesText}")
+#]=======================================================================]
 
 function(FEATURE_SUMMARY)
 # CMAKE_PARSE_ARGUMENTS(<prefix> <options> <one_value_keywords> <multi_value_keywords> args...)
@@ -482,6 +329,83 @@ function(FEATURE_SUMMARY)
 
 endfunction()
 
+#[=======================================================================[.rst:
+.. command:: set_package_properties
+
+  ::
+
+    set_package_properties(<name> PROPERTIES
+                           [ URL <url> ]
+                           [ DESCRIPTION <description> ]
+                           [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
+                           [ PURPOSE <purpose> ]
+                          )
+
+  Use this macro to set up information about the named package, which
+  can then be displayed via FEATURE_SUMMARY().  This can be done either
+  directly in the Find-module or in the project which uses the module
+  after the find_package() call.  The features for which information can
+  be set are added automatically by the find_package() command.
+
+  ``URL <url>``
+    This should be the homepage of the package, or something similar.
+    Ideally this is set already directly in the Find-module.
+
+  ``DESCRIPTION <description>``
+    A short description what that package is, at most one sentence.
+    Ideally this is set already directly in the Find-module.
+
+  ``TYPE <type>``
+    What type of dependency has the using project on that package.
+    Default is ``OPTIONAL``.  In this case it is a package which can be used
+    by the project when available at buildtime, but it also work without.
+    ``RECOMMENDED`` is similar to ``OPTIONAL``, i.e.  the project will build if
+    the package is not present, but the functionality of the resulting
+    binaries will be severly limited.  If a ``REQUIRED`` package is not
+    available at buildtime, the project may not even build.  This can be
+    combined with the ``FATAL_ON_MISSING_REQUIRED_PACKAGES`` argument for
+    ``feature_summary()``.  Last, a ``RUNTIME`` package is a package which is
+    actually not used at all during the build, but which is required for
+    actually running the resulting binaries.  So if such a package is
+    missing, the project can still be built, but it may not work later on.
+    If ``set_package_properties()`` is called multiple times for the same
+    package with different TYPEs, the ``TYPE`` is only changed to higher
+    TYPEs (``RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED``), lower TYPEs are
+    ignored.  The ``TYPE`` property is project-specific, so it cannot be set
+    by the Find-module, but must be set in the project.
+
+
+  ``PURPOSE <purpose>``
+    This describes which features this package enables in the
+    project, i.e.  it tells the user what functionality he gets in the
+    resulting binaries.  If set_package_properties() is called multiple
+    times for a package, all PURPOSE properties are appended to a list of
+    purposes of the package in the project.  As the TYPE property, also
+    the PURPOSE property is project-specific, so it cannot be set by the
+    Find-module, but must be set in the project.
+
+  Example for setting the info for a package:
+
+  .. code-block:: cmake
+
+    find_package(LibXml2)
+    set_package_properties(LibXml2 PROPERTIES
+                           DESCRIPTION "A XML processing library."
+                           URL "http://xmlsoft.org/")
+    # or
+    set_package_properties(LibXml2 PROPERTIES
+                           TYPE RECOMMENDED
+                           PURPOSE "Enables HTML-import in MyWordProcessor")
+    # or
+    set_package_properties(LibXml2 PROPERTIES
+                           TYPE OPTIONAL
+                           PURPOSE "Enables odt-export in MyWordProcessor")
+
+    find_package(DBUS)
+    set_package_properties(DBUS PROPERTIES
+      TYPE RUNTIME
+      PURPOSE "Necessary to disable the screensaver during a presentation")
+#]=======================================================================]
 function(SET_PACKAGE_PROPERTIES _name _props)
   if(NOT "${_props}" STREQUAL "PROPERTIES")
     message(FATAL_ERROR "PROPERTIES keyword is missing in SET_PACKAGE_PROPERTIES() call.")
@@ -545,6 +469,26 @@ function(SET_PACKAGE_PROPERTIES _name _props)
 
 endfunction()
 
+#[=======================================================================[.rst:
+.. command:: add_feature_info
+
+  ::
+
+    add_feature_info(<name> <enabled> <description>)
+
+  Use this macro to add information about a feature with the given ``<name>``.
+  ``<enabled>`` contains whether this feature is enabled or not.
+  ``<description>`` is a text describing the feature.  The information can
+  be displayed using ``feature_summary()`` for ``ENABLED_FEATURES`` and
+  ``DISABLED_FEATURES`` respectively.
+
+  Example for setting the info for a feature:
+
+  .. code-block:: cmake
+
+     option(WITH_FOO "Help for foo" ON)
+     add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
+#]=======================================================================]
 function(ADD_FEATURE_INFO _name _enabled _desc)
   if (${_enabled})
     set_property(GLOBAL APPEND PROPERTY ENABLED_FEATURES "${_name}")
@@ -558,6 +502,25 @@ endfunction()
 
 # The stuff below is only kept for compatibility
 
+#[=======================================================================[.rst:
+Legacy Macros
+^^^^^^^^^^^^^
+
+The following macros are provided for compatibility with previous
+CMake versions:
+
+.. command:: set_package_info
+
+  ::
+
+    set_package_info(<name> <description> [ <url> [<purpose>] ])
+
+  Use this macro to set up information about the named package, which
+  can then be displayed via ``feature_summary()``.  This can be done either
+  directly in the Find-module or in the project which uses the module
+  after the :command:`find_package` call.  The features for which information
+  can be set are added automatically by the ``find_package()`` command.
+#]=======================================================================]
 function(SET_PACKAGE_INFO _name _desc)
   unset(_url)
   unset(_purpose)
@@ -576,20 +539,51 @@ function(SET_PACKAGE_INFO _name _desc)
   endif()
 endfunction()
 
+#[=======================================================================[.rst:
+.. command:: set_feature_info
+
+  ::
+
+    set_feature_info(<name> <description> [<url>])
 
+  Does the same as::
 
+    set_package_info(<name> <description> <url>)
+#]=======================================================================]
 function(SET_FEATURE_INFO)
   SET_PACKAGE_INFO(${ARGN})
 endfunction()
 
+#[=======================================================================[.rst:
+.. command:: print_enabled_features
 
+  ::
 
+    print_enabled_features()
+
+  Does the same as
+
+  .. code-block:: cmake
+
+    feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
+#]=======================================================================]
 function(PRINT_ENABLED_FEATURES)
   FEATURE_SUMMARY(WHAT ENABLED_FEATURES  DESCRIPTION "Enabled features:")
 endfunction()
 
+#[=======================================================================[.rst:
+.. command:: print_disabled_features
 
+  ::
 
+    print_disabled_features()
+
+  Does the same as
+
+  .. code-block:: cmake
+
+    feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
+#]=======================================================================]
 function(PRINT_DISABLED_FEATURES)
   FEATURE_SUMMARY(WHAT DISABLED_FEATURES  DESCRIPTION "Disabled features:")
 endfunction()