Add documentation generation using Sphinx

This is deliberately modelled very closely on CMake's documentation
system.  It's a hefty patch, because it involved changing all the
documentation to be in reStructuredText format.  I also cleaned up the
copyright/license statements at the same time.

Note that the find modules contain the full license, due to the fact
that ecm_use_find_module() copies them out of the ECM distribution.

1 files changed, 70 insertions, 59 deletions

diff --git a/modules/ECMGenerateHeaders.cmake b/modules/ECMGenerateHeaders.cmake
index 739c2117..bac50869 100644
--- a/modules/ECMGenerateHeaders.cmake
+++ b/modules/ECMGenerateHeaders.cmake
@@ -1,26 +1,23 @@
-# - Function to generate forward includes for your project
-# This module provides the function ECM_GENERATE_HEADERS
+#.rst:
+# ECMGenerateHeaders
+# ------------------
 #
-# The ECM_GENERATE_HEADERS function is used to generate C/C++ forwarding header
-# files for your project.
+# Generate C/C++ CamelCase forwarding headers.
 #
-# To be more precise, there will be two kinds of headers being generated. Lowercase
-# and CamelCase, for convenience. That means that for a class named "ClassA" in a
-# module called "Module" we will get 2 different files: Module/ClassA and
-# module/classa.h. Both these files will be including a "classa.h" file that is
-# expected to be in the headers dir (see HEADERS_DIR argument below).
+# ::
 #
-# ECM_GENERATE_HEADERS(camelcase_headers_var
-#     HEADER_NAMES ClassA [ClassB [...]]
-#     [OUTPUT_DIR output_dir]
-#     [PREFIX prefix]
-#     [REQUIRED_HEADERS variable]
-#     [RELATIVE relative_path])
+#   ecm_generate_headers(<camelcase_headers_var>
+#       HEADER_NAMES <CamelCaseHeader> [<CamelCaseHeader> [...]]
+#       [OUTPUT_DIR <output_dir>]
+#       [PREFIX <prefix>]
+#       [REQUIRED_HEADERS <variable>]
+#       [RELATIVE <relative_path>])
 #
-# The paths to the generated CamelCase headers will be appended to
-# camelcase_headers_var.
-#
-# HEADER_NAMES lists the generated CamelCase header names.
+# For each CamelCase header name passed to HEADER_NAMES, a file of that name
+# will be generated that will include a lowercased version with ``.h`` appended.
+# For example, the header ``ClassA`` will include ``classa.h``.  The file
+# locations of these generated headers will be stored in
+# <camelcase_headers_var>.
 #
 # PREFIX places the headers in subdirectories.  This should be a CamelCase name
 # like KParts, which will cause the CamelCase headers to be placed in the KParts
@@ -30,67 +27,81 @@
 # used before installation, as long as the include_directories are set
 # appropriately.
 #
-# The OUTPUT_DIR argument specifies where the files will be generated; this
-# should be within the build directory. By default, CMAKE_CURRENT_BINARY_DIR
-# will be used.  This option can be used to avoid file conflicts.
+# OUTPUT_DIR specifies where the files will be generated; this should be within
+# the build directory. By default, ``${CMAKE_CURRENT_BINARY_DIR}`` will be used.
+# This option can be used to avoid file conflicts.
 #
-# The REQUIRED_HEADERS argument specifies an output variable name where all the
-# required headers will be appended so that they can be installed together with
-# the generated ones.  This is mostly intended as a convenience so that adding a
-# new header to a project only requires specifying the CamelCase variant in the
+# REQUIRED_HEADERS specifies an output variable name where all the required
+# headers will be appended so that they can be installed together with the
+# generated ones.  This is mostly intended as a convenience so that adding a new
+# header to a project only requires specifying the CamelCase variant in the
 # CMakeLists.txt file; the lowercase variant will then be added to this
 # variable.
 #
 # The RELATIVE argument indicates where the lowercase headers can be found
 # relative to CMAKE_CURRENT_SOURCE_DIR.  It does not affect the generated
-# CamelCase files, but ECM_GENERATE_HEADERS uses it when checking that the
+# CamelCase files, but ecm_generate_headers() uses it when checking that the
 # lowercase header exists, and to generate lowercase forwarding headers when
 # PREFIX is set.
 #
 # To allow other parts of the source distribution (eg: tests) to use the
 # generated headers before installation, it may be desirable to set the
 # INCLUDE_DIRECTORIES property for the library target to output_dir.  For
-# example, if output_dir is CMAKE_CURRENT_BINARY_DIR (the default), you could do
-#   target_include_directories(MyLib
-#       PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")
+# example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the default), you could do
+#
+# .. code-block:: cmake
+#
+#   target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")
 #
 # Example usage (without PREFIX):
-# ecm_generate_headers(
-#     MyLib_FORWARDING_HEADERS
-#     HEADERS
-#         MLFoo
-#         MLBar
-#         # etc
-#     REQUIRED_HEADERS MyLib_HEADERS
-# )
-# install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
-#         DESTINATION ${CMAKE_INSTALL_PREFIX}/include
-#         COMPONENT Devel)
 #
-# Example usage (with PREFIX):
-# ecm_generate_headers(
-#     MyLib_FORWARDING_HEADERS
-#     HEADERS
-#         Foo
-#         Bar
-#         # etc
-#     PREFIX MyLib
-#     REQUIRED_HEADERS MyLib_HEADERS
-# )
-# install(FILES ${MyLib_FORWARDING_HEADERS}
-#         DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
-#         COMPONENT Devel)
-# install(FILES ${MyLib_HEADERS}
-#         DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
-#         COMPONENT Devel)
+# .. code-block:: cmake
 #
+#   ecm_generate_headers(
+#       MyLib_FORWARDING_HEADERS
+#       HEADERS
+#           MLFoo
+#           MLBar
+#           # etc
+#       REQUIRED_HEADERS MyLib_HEADERS
+#   )
+#   install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
+#           DESTINATION ${CMAKE_INSTALL_PREFIX}/include
+#           COMPONENT Devel)
 #
+# Example usage (with PREFIX):
+#
+# .. code-block:: cmake
+#
+#   ecm_generate_headers(
+#       MyLib_FORWARDING_HEADERS
+#       HEADERS
+#           Foo
+#           Bar
+#           # etc
+#       PREFIX MyLib
+#       REQUIRED_HEADERS MyLib_HEADERS
+#   )
+#   install(FILES ${MyLib_FORWARDING_HEADERS}
+#           DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
+#           COMPONENT Devel)
+#   install(FILES ${MyLib_HEADERS}
+#           DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
+#           COMPONENT Devel)
+
+#=============================================================================
 # Copyright 2013 Aleix Pol Gonzalez <aleixpol@blue-systems.com>
 # Copyright 2014 Alex Merry <alex.merry@kdemail.net>
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
 #
+# This software is distributed WITHOUT ANY WARRANTY; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the License for more information.
+#=============================================================================
+# (To distribute this file outside of extra-cmake-modules, substitute the full
+#  License text for the above reference.)
 
 include(CMakeParseArguments)