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.

60 files changed, 1693 insertions, 548 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 7ac655a6..0f752aa3 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -11,26 +11,15 @@ set(ECM_VERSION ${ECM_MAJOR_VERSION}.${ECM_MINOR_VERSION}.${ECM_PATCH_VERSION})
 enable_testing()
 add_subdirectory(tests)
 
-set(SHARE_INSTALL_DIR share/ECM )
-set(MODULES_INSTALL_DIR ${SHARE_INSTALL_DIR}/modules/)
-set(KDE_MODULES_INSTALL_DIR ${SHARE_INSTALL_DIR}/kde-modules/)
-set(FIND_MODULES_INSTALL_DIR ${SHARE_INSTALL_DIR}/find-modules/)
-set(CMAKECONFIG_INSTALL_DIR ${SHARE_INSTALL_DIR}/cmake/)
-set(DOC_INSTALL_DIR ${SHARE_INSTALL_DIR}/doc/)
-
-# create and install docs
-# add_custom_target(ManPage ALL
-#                     COMMAND ${CMAKE_COMMAND} -DCMAKE_MODULE_PATH=${CMAKE_SOURCE_DIR}/modules\;${CMAKE_SOURCE_DIR}/find-modules\;${CMAKE_SOURCE_DIR}/kde-modules --help-custom-modules "${CMAKE_BINARY_DIR}/extra-cmake-modules.7"
-#                     COMMAND ${CMAKE_COMMAND} -DCMAKE_MODULE_PATH=${CMAKE_SOURCE_DIR}/modules\;${CMAKE_SOURCE_DIR}/find-modules\;${CMAKE_SOURCE_DIR}/kde-modules --help-custom-modules "${CMAKE_BINARY_DIR}/extra-cmake-modules.html"
-#                     COMMAND ${CMAKE_COMMAND} -DCMAKE_MODULE_PATH=${CMAKE_SOURCE_DIR}/modules\;${CMAKE_SOURCE_DIR}/find-modules\;${CMAKE_SOURCE_DIR}/kde-modules --help-custom-modules "${CMAKE_BINARY_DIR}/extra-cmake-modules.txt"
-#                     VERBATIM
-#                  )
-
-# install(FILES "${CMAKE_BINARY_DIR}/extra-cmake-modules.7" DESTINATION man/man7/)
-
-# install(FILES "${CMAKE_BINARY_DIR}/extra-cmake-modules.txt" "${CMAKE_BINARY_DIR}/extra-cmake-modules.html"
-#         DESTINATION ${DOC_INSTALL_DIR})
-
+set(SHARE_INSTALL_DIR share)
+set(MODULES_INSTALL_DIR ${SHARE_INSTALL_DIR}/ECM/modules/)
+set(KDE_MODULES_INSTALL_DIR ${SHARE_INSTALL_DIR}/ECM/kde-modules/)
+set(FIND_MODULES_INSTALL_DIR ${SHARE_INSTALL_DIR}/ECM/find-modules/)
+set(CMAKECONFIG_INSTALL_DIR ${SHARE_INSTALL_DIR}/ECM/cmake/)
+set(DOC_INSTALL_DIR ${SHARE_INSTALL_DIR}/doc/ECM)
+set(MAN_INSTALL_DIR ${SHARE_INSTALL_DIR}/man)
+
+add_subdirectory(docs)
 
 file(GLOB installModuleFiles ${CMAKE_SOURCE_DIR}/modules/*[^~])
 install(FILES ${installModuleFiles} DESTINATION ${MODULES_INSTALL_DIR})
diff --git a/README.md b/README.md
deleted file mode 100644
index baa80c33..00000000
--- a/README.md
+++ /dev/null
@@ -1,94 +0,0 @@
-Extra CMake Modules
-===================
-
-Additional functionality for the CMake build system
-
-
-Introduction
-------------
-
-The Extra CMake Modules package, or ECM, adds to the modules provided by CMake,
-including both ones used by `find_package()` to find common software and ones
-that can be used directly in `CMakeLists.txt` files to perform common tasks.
-
-In addition, it provides common build settings used in software produced by the
-KDE community.
-
-While the driving force of this module is to reduce duplication in CMake scripts
-across KDE software, it is intended to be useful for any software that uses the
-CMake build system.
-
-
-Usage
------
-
-To use ECM, add the following to your `CMakeLists.txt`:
-
-    find_package(ECM <ecm-version> REQUIRED NO_MODULE)
-    set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
-
-(note that you may want to append `${ECM_MODULE_PATH}` to `CMAKE_MODULE_PATH`
-instead).  You can then just include the modules you require, or use
-`find_package()` as needed.  For example:
-
-    include(ECMInstallIcons)
-
-Developers of KDE software will often want to use the KDE standard settings
-provided by ECM; they can do the following:
-
-    find_package(ECM <ecm-version> REQUIRED NO_MODULE)
-    set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH} ${ECM_KDE_MODULE_DIR})
-    include(KDEInstallDirs)
-    include(KDECompilerSettings)
-    include(KDECMakeSettings)
-
-Note that any combination of the above includes can be used if you only want
-some of the settings.  Some of the functionality of `KDECMakeSettings` can also
-be selectively disabled; see the documentation at the top of
-`kde-modules/KDECMakeSettings.cmake` for more details.
-
-
-Organization
-------------
-
-This module is organised as follows:
-
-- `attic/` contains most of the CMake modules shipped with kdelibs 4.  These
-  can be used to form the basis of cleaned-up modules, either for inclusion in
-  ECM or for private use in a project.
-- `find-modules/` contains the modules used by CMake's `find_package()` command.
-- `kde-modules/` contains modules that provide some common settings for KDE
-  applications and frameworks.
-- `modules/` contains the modules that should be included directly by CMake
-  scripts, other than those in `kde-modules/`.
-- `tests/` contains automated tests for the functionality provided by ECM
-  modules.
-
-
-Creating Modules
-----------------
-
-Proposed new modules should be submitted using the
-[KDE Review Board instance][RB], and be assigned to the `buildsystem`,
-`extracmakemodules` and `kdeframeworks` groups.  You should be able to point to
-two separate projects that will make use of the module.  See the `docs/`
-directory for more information on writing the modules themselves.
-
-[RB]: https://git.reviewboard.kde.org/
-
-
-License
--------
-
-All code in this repository is licensed under the [BSD 2-Clause license][1].
-
-[1]: http://opensource.org/licenses/BSD-2-Clause
-
-
-Links
------
-
-- Home page: <https://projects.kde.org/projects/kdesupport/extra-cmake-modules>
-- Mailing list: <https://mail.kde.org/mailman/listinfo/kde-buildsystem>
-- IRC channel: \#kde-devel on Freenode
-- Git repository: <https://projects.kde.org/projects/kdesupport/extra-cmake-modules/repository>
diff --git a/README.rst b/README.rst
new file mode 100644
index 00000000..a079cae5
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,98 @@
+Extra CMake Modules
+*******************
+
+Introduction
+============
+
+The Extra CMake Modules package, or ECM, adds to the modules provided by CMake,
+including both ones used by ``find_package()`` to find common software and ones
+that can be used directly in ``CMakeLists.txt`` files to perform common tasks.
+
+In addition, it provides common build settings used in software produced by the
+KDE community.
+
+While the driving force of this module is to reduce duplication in CMake scripts
+across KDE software, it is intended to be useful for any software that uses the
+CMake build system.
+
+
+Usage
+=====
+
+To use ECM, add the following to your ``CMakeLists.txt``:
+
+.. code-block:: cmake
+
+  find_package(ECM REQUIRED NO_MODULE)
+  set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
+
+(note that you may want to append ``${ECM_MODULE_PATH}`` to
+``CMAKE_MODULE_PATH`` instead).  You can then just include the modules you
+require, or use ``find_package()`` as needed.  For example:
+
+.. code-block:: cmake
+
+  include(ECMInstallIcons)
+
+Developers of KDE software will often want to use the KDE standard settings
+provided by ECM; they can do the following:
+
+.. code-block:: cmake
+
+  find_package(ECM REQUIRED NO_MODULE)
+  set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
+  include(KDEInstallDirs)
+  include(KDECompilerSettings)
+  include(KDECMakeSettings)
+
+Note that any combination of the above includes can be used if you only want
+some of the settings.  Some of the functionality of
+:kde-module:`KDECMakeSettings` can also be selectively disabled.
+
+
+Organization
+------------
+
+ECM provides three different types of modules.
+
+* Core modules provide helpful macros for use in project CMake scripts.
+  See :manual:`ecm-modules(7)` for more information.
+* Find modules extend the functionality of CMake's ``find_package()`` command.
+  See :manual:`ecm-find-modules(7)` for more information.
+* KDE modules provide common settings for software produced by KDE; much of this
+  may also be useful to other projects.  See :manual:`ecm-kde-modules(7)` for
+  more information.
+
+The ``${ECM_MODULE_DIR}``, ``${ECM_FIND_MODULE_DIR}`` and
+``${ECM_KDE_MODULE_DIR}`` variables may be used instead of
+``${ECM_MODULE_PATH}`` if you only need some of this functionality.
+
+
+Submitting Modules
+==================
+
+Proposed new modules should be submitted using the
+`KDE Review Board instance`_, and be assigned to the ``buildsystem``,
+``extracmakemodules`` and ``kdeframeworks`` groups.  You should be able to point to
+two separate projects that will make use of the module.
+
+.. _KDE Review Board instance: https://git.reviewboard.kde.org/
+
+
+License
+=======
+
+All code is licensed under the `BSD 3-Clause license`_.
+
+.. _BSD 3-Clause license: http://opensource.org/licenses/BSD-3-Clause
+
+
+.. only:: html
+
+  Links
+  =====
+
+  * `Home page <https://projects.kde.org/projects/kdesupport/extra-cmake-modules>`_
+  * `Mailing list <https://mail.kde.org/mailman/listinfo/kde-buildsystem>`_
+  * IRC channel: #kde-devel on Freenode
+  * `Git repository <https://projects.kde.org/projects/kdesupport/extra-cmake-modules/repository>`_
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
new file mode 100644
index 00000000..ff04e7de
--- /dev/null
+++ b/docs/CMakeLists.txt
@@ -0,0 +1,125 @@
+#=============================================================================
+# CMake - Cross Platform Makefile Generator
+# Copyright 2000-2013 Kitware, Inc., Insight Software Consortium
+# Copyright 2014 Alex Merry <alex.merry@kde.org>
+#
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file Copyright.txt 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.
+#=============================================================================
+
+# Distros sometimes rename Python executables to allow for parallel
+# installation of Python2 and Python3 versions
+find_program(SPHINX_EXECUTABLE
+    NAMES
+        sphinx-build
+        sphinx-build2
+        sphinx-build3
+    DOC "Sphinx Documentation Builder (sphinx-doc.org)"
+)
+if(SPHINX_EXECUTABLE)
+    set(build_docs_default ON)
+else()
+    set(build_docs_default OFF)
+endif()
+
+option(BUILD_HTML_DOCS "Build html help with Sphinx" ${build_docs_default})
+option(BUILD_MAN_DOCS "Build man pages with Sphinx" ${build_docs_default})
+option(BUILD_QTHELP_DOCS "Build Qt help with Sphinx" OFF)
+
+if(NOT BUILD_HTML_DOCS AND NOT BUILD_MAN_DOCS AND NOT BUILD_QTHELP_DOCS)
+    return()
+elseif(NOT SPHINX_EXECUTABLE)
+    message(FATAL_ERROR "SPHINX_EXECUTABLE (sphinx-build) was not found!")
+endif()
+
+# the docs/ directory
+set(conf_docs "${CMAKE_CURRENT_SOURCE_DIR}")
+# where cmake.py and other sphinx files are
+set(conf_path "${CMAKE_CURRENT_SOURCE_DIR}/sphinx")
+set(conf_version "${extra-cmake-modules_VERSION_MAJOR}.${extra-cmake-modules_VERSION_MINOR}.${extra-cmake-modules_VERSION_PATCH}")
+set(conf_release "${extra-cmake-modules_VERSION}")
+configure_file(sphinx/conf.py.in conf.py @ONLY)
+
+set(doc_formats "")
+if(BUILD_HTML_DOCS)
+    list(APPEND doc_formats html)
+endif()
+if(BUILD_MAN_DOCS)
+    list(APPEND doc_formats man)
+endif()
+if(BUILD_QTHELP_DOCS)
+    find_program(QCOLLECTIONGENERATOR_EXECUTABLE
+        NAMES qcollectiongenerator
+        DOC "qcollectiongenerator tool"
+    )
+    if (NOT QCOLLECTIONGENERATOR_EXECUTABLE)
+        message(FATAL_ERROR "QCOLLECTIONGENERATOR_EXECUTABLE (qcollectiongenerator) not found!")
+    endif()
+    list(APPEND doc_formats qthelp)
+
+    set(qthelp_extra_commands
+        COMMAND
+            qcollectiongenerator
+            ${CMAKE_CURRENT_BINARY_DIR}/qthelp/extra-cmake-modules.qhcp
+    )
+endif()
+
+
+set(doc_format_outputs "")
+set(doc_format_last "")
+foreach(format ${doc_formats})
+    set(doc_format_output "doc_format_${format}")
+    set(doc_format_log "build-${format}.log")
+    add_custom_command(
+        OUTPUT ${doc_format_output}
+        COMMAND
+            ${SPHINX_EXECUTABLE}
+            -c ${CMAKE_CURRENT_BINARY_DIR}
+            -d ${CMAKE_CURRENT_BINARY_DIR}/doctrees
+            -b ${format}
+            ${CMAKE_CURRENT_SOURCE_DIR}
+            ${CMAKE_CURRENT_BINARY_DIR}/${format}
+            > ${doc_format_log} # log stdout, pass stderr
+        DEPENDS ${doc_format_last}
+        COMMENT "sphinx-build ${format}: see ${CMAKE_CURRENT_BINARY_DIR}/${doc_format_log}"
+        VERBATIM
+    )
+    set_property(SOURCE ${doc_format_output} PROPERTY SYMBOLIC 1)
+    list(APPEND doc_format_outputs ${doc_format_output})
+    set(doc_format_last ${doc_format_output})
+endforeach()
+
+add_custom_target(documentation ALL DEPENDS ${doc_format_outputs})
+
+if(BUILD_MAN_DOCS)
+    file(GLOB man_rst RELATIVE ${extra-cmake-modules_SOURCE_DIR}/docs/manual
+    ${extra-cmake-modules_SOURCE_DIR}/docs/manual/*.[1-9].rst)
+    foreach(m ${man_rst})
+        if("x${m}" MATCHES "^x(.+)\\.([1-9])\\.rst$")
+            set(name "${CMAKE_MATCH_1}")
+            set(sec "${CMAKE_MATCH_2}")
+            install(
+                FILES ${CMAKE_CURRENT_BINARY_DIR}/man/${name}.${sec}
+                DESTINATION ${MAN_INSTALL_DIR}/man${sec}
+            )
+        endif()
+    endforeach()
+endif()
+if(BUILD_HTML_DOCS)
+    install(
+        DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html
+        DESTINATION ${DOC_INSTALL_DIR}
+        PATTERN .buildinfo EXCLUDE
+        PATTERN objects.inv EXCLUDE
+    )
+endif()
+if(BUILD_QTHELP_DOCS)
+    install(
+        FILES ${CMAKE_CURRENT_BINARY_DIR}/qthelp/extra-cmake-modules.qch
+        DESTINATION ${DOC_INSTALL_DIR}
+    )
+endif()
diff --git a/docs/find-module/FindEGL.rst b/docs/find-module/FindEGL.rst
new file mode 100644
index 00000000..6eb9710c
--- /dev/null
+++ b/docs/find-module/FindEGL.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../find-modules/FindEGL.cmake
diff --git a/docs/find-module/FindOpenEXR.rst b/docs/find-module/FindOpenEXR.rst
new file mode 100644
index 00000000..abefc855
--- /dev/null
+++ b/docs/find-module/FindOpenEXR.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../find-modules/FindOpenEXR.cmake
diff --git a/docs/find-module/FindSharedMimeInfo.rst b/docs/find-module/FindSharedMimeInfo.rst
new file mode 100644
index 00000000..678eb516
--- /dev/null
+++ b/docs/find-module/FindSharedMimeInfo.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../find-modules/FindSharedMimeInfo.cmake
diff --git a/docs/find-module/FindWayland.rst b/docs/find-module/FindWayland.rst
new file mode 100644
index 00000000..c64c6d85
--- /dev/null
+++ b/docs/find-module/FindWayland.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../find-modules/FindWayland.cmake
diff --git a/docs/find-module/FindX11_XCB.rst b/docs/find-module/FindX11_XCB.rst
new file mode 100644
index 00000000..30b92464
--- /dev/null
+++ b/docs/find-module/FindX11_XCB.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../find-modules/FindX11_XCB.cmake
diff --git a/docs/find-module/FindXCB.rst b/docs/find-module/FindXCB.rst
new file mode 100644
index 00000000..31e22282
--- /dev/null
+++ b/docs/find-module/FindXCB.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../find-modules/FindXCB.cmake
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 00000000..1441005f
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,19 @@
+.. title:: Extra CMake Modules Reference Documentation
+
+Reference Manuals
+#################
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   /manual/ecm.7
+   /manual/*
+
+.. only:: html
+
+ Index and Search
+ ################
+
+ * :ref:`genindex`
+ * :ref:`search`
diff --git a/docs/kde-module/KDECMakeSettings.rst b/docs/kde-module/KDECMakeSettings.rst
new file mode 100644
index 00000000..48ab140e
--- /dev/null
+++ b/docs/kde-module/KDECMakeSettings.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../kde-modules/KDECMakeSettings.cmake
diff --git a/docs/kde-module/KDECompilerSettings.rst b/docs/kde-module/KDECompilerSettings.rst
new file mode 100644
index 00000000..28f3e9c5
--- /dev/null
+++ b/docs/kde-module/KDECompilerSettings.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../kde-modules/KDECompilerSettings.cmake
diff --git a/docs/kde-module/KDEFrameworkCompilerSettings.rst b/docs/kde-module/KDEFrameworkCompilerSettings.rst
new file mode 100644
index 00000000..6b8d7df5
--- /dev/null
+++ b/docs/kde-module/KDEFrameworkCompilerSettings.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../kde-modules/KDEFrameworkCompilerSettings.cmake
diff --git a/docs/kde-module/KDEInstallDirs.rst b/docs/kde-module/KDEInstallDirs.rst
new file mode 100644
index 00000000..06435172
--- /dev/null
+++ b/docs/kde-module/KDEInstallDirs.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../kde-modules/KDEInstallDirs.cmake
diff --git a/docs/manual/ecm-find-modules.7.rst b/docs/manual/ecm-find-modules.7.rst
new file mode 100644
index 00000000..4e3fc984
--- /dev/null
+++ b/docs/manual/ecm-find-modules.7.rst
@@ -0,0 +1,18 @@
+.. ecm-manual-description: ECM Find Modules Reference
+
+ecm-find-modules(7)
+*******************
+
+.. only:: html or latex
+
+   .. contents::
+
+All Find Modules
+================
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   /find-module/*
+
diff --git a/docs/manual/ecm-kde-modules.7.rst b/docs/manual/ecm-kde-modules.7.rst
new file mode 100644
index 00000000..b3dffd77
--- /dev/null
+++ b/docs/manual/ecm-kde-modules.7.rst
@@ -0,0 +1,18 @@
+.. ecm-manual-description: ECM KDE Modules Reference
+
+ecm-kde-modules(7)
+******************
+
+.. only:: html or latex
+
+   .. contents::
+
+All KDE Modules
+===============
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   /kde-module/*
+
diff --git a/docs/manual/ecm-modules.7.rst b/docs/manual/ecm-modules.7.rst
new file mode 100644
index 00000000..70b09f5e
--- /dev/null
+++ b/docs/manual/ecm-modules.7.rst
@@ -0,0 +1,18 @@
+.. ecm-manual-description: ECM Modules Reference
+
+ecm-modules(7)
+**************
+
+.. only:: html or latex
+
+   .. contents::
+
+All Modules
+===========
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   /module/*
+
diff --git a/docs/manual/ecm.7.rst b/docs/manual/ecm.7.rst
new file mode 100644
index 00000000..fdc444a6
--- /dev/null
+++ b/docs/manual/ecm.7.rst
@@ -0,0 +1,11 @@
+.. ecm-manual-description: Extra CMake Modules
+
+ecm(7)
+******
+
+.. only:: html or latex
+
+   .. contents::
+
+.. include:: ../../README.rst
+  :start-line: 2
diff --git a/docs/module/ECMAddTests.rst b/docs/module/ECMAddTests.rst
new file mode 100644
index 00000000..f971953a
--- /dev/null
+++ b/docs/module/ECMAddTests.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMAddTests.cmake
diff --git a/docs/module/ECMCreateQmFromPoFiles.rst b/docs/module/ECMCreateQmFromPoFiles.rst
new file mode 100644
index 00000000..13340c0a
--- /dev/null
+++ b/docs/module/ECMCreateQmFromPoFiles.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMCreateQmFromPoFiles.cmake
diff --git a/docs/module/ECMDBusAddActivationService.rst b/docs/module/ECMDBusAddActivationService.rst
new file mode 100644
index 00000000..2052faeb
--- /dev/null
+++ b/docs/module/ECMDBusAddActivationService.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMDBusAddActivationService.cmake
diff --git a/docs/module/ECMFindModuleHelpers.rst b/docs/module/ECMFindModuleHelpers.rst
new file mode 100644
index 00000000..bec8f822
--- /dev/null
+++ b/docs/module/ECMFindModuleHelpers.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMFindModuleHelpers.cmake
diff --git a/docs/module/ECMGenerateHeaders.rst b/docs/module/ECMGenerateHeaders.rst
new file mode 100644
index 00000000..ad3e4819
--- /dev/null
+++ b/docs/module/ECMGenerateHeaders.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMGenerateHeaders.cmake
diff --git a/docs/module/ECMGeneratePriFile.rst b/docs/module/ECMGeneratePriFile.rst
new file mode 100644
index 00000000..1cb4d6a4
--- /dev/null
+++ b/docs/module/ECMGeneratePriFile.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMGeneratePriFile.cmake
diff --git a/docs/module/ECMInstallIcons.rst b/docs/module/ECMInstallIcons.rst
new file mode 100644
index 00000000..7bb70ea5
--- /dev/null
+++ b/docs/module/ECMInstallIcons.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMInstallIcons.cmake
diff --git a/docs/module/ECMMarkAsTest.rst b/docs/module/ECMMarkAsTest.rst
new file mode 100644
index 00000000..8b6a8752
--- /dev/null
+++ b/docs/module/ECMMarkAsTest.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMMarkAsTest.cmake
diff --git a/docs/module/ECMMarkNonGuiExecutable.rst b/docs/module/ECMMarkNonGuiExecutable.rst
new file mode 100644
index 00000000..2684fee6
--- /dev/null
+++ b/docs/module/ECMMarkNonGuiExecutable.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMMarkNonGuiExecutable.cmake
diff --git a/docs/module/ECMOptionalAddSubdirectory.rst b/docs/module/ECMOptionalAddSubdirectory.rst
new file mode 100644
index 00000000..af9595ec
--- /dev/null
+++ b/docs/module/ECMOptionalAddSubdirectory.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMOptionalAddSubdirectory.cmake
diff --git a/docs/module/ECMPackageConfigHelpers.rst b/docs/module/ECMPackageConfigHelpers.rst
new file mode 100644
index 00000000..21102c4f
--- /dev/null
+++ b/docs/module/ECMPackageConfigHelpers.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMPackageConfigHelpers.cmake
diff --git a/docs/module/ECMSetupVersion.rst b/docs/module/ECMSetupVersion.rst
new file mode 100644
index 00000000..f984a81f
--- /dev/null
+++ b/docs/module/ECMSetupVersion.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMSetupVersion.cmake
diff --git a/docs/module/ECMUseFindModules.rst b/docs/module/ECMUseFindModules.rst
new file mode 100644
index 00000000..48bbf35a
--- /dev/null
+++ b/docs/module/ECMUseFindModules.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMUseFindModules.cmake
diff --git a/docs/sphinx/.gitignore b/docs/sphinx/.gitignore
new file mode 100644
index 00000000..0d20b648
--- /dev/null
+++ b/docs/sphinx/.gitignore
@@ -0,0 +1 @@
+*.pyc
diff --git a/docs/sphinx/conf.py.in b/docs/sphinx/conf.py.in
new file mode 100644
index 00000000..24ba82c8
--- /dev/null
+++ b/docs/sphinx/conf.py.in
@@ -0,0 +1,63 @@
+#=============================================================================
+# CMake - Cross Platform Makefile Generator
+# Copyright 2000-2013 Kitware, Inc., Insight Software Consortium
+#
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file Copyright.txt 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.
+#=============================================================================
+import sys
+import os
+import re
+import glob
+
+sys.path.insert(0, r'@conf_path@')
+
+source_suffix = '.rst'
+master_doc = 'index'
+
+project = 'Extra CMake Modules'
+copyright = 'KDE Developers'
+version = '@conf_version@' # feature version
+release = '@conf_release@' # full version string
+
+primary_domain = 'ecm'
+
+exclude_patterns = []
+
+extensions = ['ecm']
+templates_path = ['@conf_path@/templates']
+
+ecm_manuals = sorted(glob.glob(r'@conf_docs@/manual/*.rst'))
+ecm_manual_description = re.compile('^\.\. ecm-manual-description:(.*)$')
+man_pages = []
+for fpath in ecm_manuals:
+    try:
+        name, sec, rst = os.path.basename(fpath).split('.')
+        desc = None
+        f = open(fpath, 'r')
+        for l in f:
+            m = ecm_manual_description.match(l)
+            if m:
+                desc = m.group(1).strip()
+                break
+        f.close()
+        if desc:
+            man_pages.append(('manual/%s.%s' % (name, sec),
+                              name, desc, [], int(sec)))
+        else:
+            sys.stderr.write("ERROR: No ecm-manual-description in '%s'\n" % fpath)
+    except Exception, e:
+        sys.stderr.write("ERROR: %s\n" % str(e))
+man_show_urls = False
+
+html_show_sourcelink = True
+html_static_path = ['@conf_path@/static']
+html_style = 'ecm.css'
+html_theme = 'default'
+html_title = 'Extra CMake Modules %s Documentation' % release
+html_short_title = '%s Documentation' % release
+html_favicon = '@conf_path@/kde-favicon.ico'
diff --git a/docs/sphinx/ecm.py b/docs/sphinx/ecm.py
new file mode 100644
index 00000000..9b76e1a9
--- /dev/null
+++ b/docs/sphinx/ecm.py
@@ -0,0 +1,301 @@
+# Copyright 2014 Alex Merry <alex.merry@kde.org>
+# Based on cmake.py from CMake:
+# Copyright 2000-2013 Kitware, Inc., Insight Software Consortium
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. The name of the author may not be used to endorse or promote products
+#    derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+import os
+import re
+
+# Monkey patch for pygments reporting an error when generator expressions are
+# used.
+# https://bitbucket.org/birkenfeld/pygments-main/issue/942/cmake-generator-expressions-not-handled
+from pygments.lexers import CMakeLexer
+from pygments.token import Name, Operator
+from pygments.lexer import bygroups
+CMakeLexer.tokens["args"].append(('(\\$<)(.+?)(>)',
+                                  bygroups(Operator, Name.Variable, Operator)))
+
+# Monkey patch for sphinx generating invalid content for qcollectiongenerator
+# https://bitbucket.org/birkenfeld/sphinx/issue/1435/qthelp-builder-should-htmlescape-keywords
+from sphinx.util.pycompat import htmlescape
+from sphinx.builders.qthelp import QtHelpBuilder
+old_build_keywords = QtHelpBuilder.build_keywords
+def new_build_keywords(self, title, refs, subitems):
+  old_items = old_build_keywords(self, title, refs, subitems)
+  new_items = []
+  for item in old_items:
+    before, rest = item.split("ref=\"", 1)
+    ref, after = rest.split("\"")
+    if ("<" in ref and ">" in ref):
+      new_items.append(before + "ref=\"" + htmlescape(ref) + "\"" + after)
+    else:
+      new_items.append(item)
+  return new_items
+QtHelpBuilder.build_keywords = new_build_keywords
+
+
+from docutils.parsers.rst import Directive, directives
+from docutils.transforms import Transform
+try:
+    from docutils.utils.error_reporting import SafeString, ErrorString
+except ImportError:
+    # error_reporting was not in utils before version 0.11:
+    from docutils.error_reporting import SafeString, ErrorString
+
+from docutils import io, nodes
+
+from sphinx.directives import ObjectDescription
+from sphinx.domains import Domain, ObjType
+from sphinx.roles import XRefRole
+from sphinx.util.nodes import make_refnode
+from sphinx import addnodes
+
+class ECMModule(Directive):
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {'encoding': directives.encoding}
+
+    def __init__(self, *args, **keys):
+        self.re_start = re.compile(r'^#\[(?P<eq>=*)\[\.rst:$')
+        Directive.__init__(self, *args, **keys)
+
+    def run(self):
+        settings = self.state.document.settings
+        if not settings.file_insertion_enabled:
+            raise self.warning('"%s" directive disabled.' % self.name)
+
+        env = self.state.document.settings.env
+        rel_path, path = env.relfn2path(self.arguments[0])
+        path = os.path.normpath(path)
+        encoding = self.options.get('encoding', settings.input_encoding)
+        e_handler = settings.input_encoding_error_handler
+        try:
+            settings.record_dependencies.add(path)
+            f = io.FileInput(source_path=path, encoding=encoding,
+                             error_handler=e_handler)
+        except UnicodeEncodeError, error:
+            raise self.severe('Problems with "%s" directive path:\n'
+                              'Cannot encode input file path "%s" '
+                              '(wrong locale?).' %
+                              (self.name, SafeString(path)))
+        except IOError, error:
+            raise self.severe('Problems with "%s" directive path:\n%s.' %
+                      (self.name, ErrorString(error)))
+        raw_lines = f.read().splitlines()
+        f.close()
+        rst = None
+        lines = []
+        for line in raw_lines:
+            if rst is not None and rst != '#':
+                # Bracket mode: check for end bracket
+                pos = line.find(rst)
+                if pos >= 0:
+                    if line[0] == '#':
+                        line = ''
+                    else:
+                        line = line[0:pos]
+                    rst = None
+            else:
+                # Line mode: check for .rst start (bracket or line)
+                m = self.re_start.match(line)
+                if m:
+                    rst = ']%s]' % m.group('eq')
+                    line = ''
+                elif line == '#.rst:':
+                    rst = '#'
+                    line = ''
+                elif rst == '#':
+                    if line == '#' or line[:2] == '# ':
+                        line = line[2:]
+                    else:
+                        rst = None
+                        line = ''
+                elif rst is None:
+                    line = ''
+            lines.append(line)
+        if rst is not None and rst != '#':
+            raise self.warning('"%s" found unclosed bracket "#[%s[.rst:" in %s' %
+                               (self.name, rst[1:-1], path))
+        self.state_machine.insert_input(lines, path)
+        return []
+
+class _ecm_index_entry:
+    def __init__(self, desc):
+        self.desc = desc
+
+    def __call__(self, title, targetid):
+        return ('pair', u'%s ; %s' % (self.desc, title), targetid, 'main')
+
+_ecm_index_objs = {
+    'manual':      _ecm_index_entry('manual'),
+    'module':      _ecm_index_entry('module'),
+    'find-module': _ecm_index_entry('find-module'),
+    'kde-module':  _ecm_index_entry('kde-module'),
+    }
+
+def _ecm_object_inventory(env, document, line, objtype, targetid):
+    inv = env.domaindata['ecm']['objects']
+    if targetid in inv:
+        document.reporter.warning(
+            'ECM object "%s" also described in "%s".' %
+            (targetid, env.doc2path(inv[targetid][0])), line=line)
+    inv[targetid] = (env.docname, objtype)
+
+class ECMTransform(Transform):
+
+    # Run this transform early since we insert nodes we want
+    # treated as if they were written in the documents.
+    default_priority = 210
+
+    def __init__(self, document, startnode):
+        Transform.__init__(self, document, startnode)
+        self.titles = {}
+
+    def parse_title(self, docname):
+        """Parse a document title as the first line starting in [A-Za-z0-9<]
+           or fall back to the document basename if no such line exists.
+           Return the title or False if the document file does not exist.
+        """
+        env = self.document.settings.env
+        title = self.titles.get(docname)
+        if title is None:
+            fname = os.path.join(env.srcdir, docname+'.rst')
+            try:
+                f = open(fname, 'r')
+            except IOError:
+                title = False
+            else:
+                for line in f:
+                    if len(line) > 0 and (line[0].isalnum() or line[0] == '<'):
+                        title = line.rstrip()
+                        break
+                f.close()
+                if title is None:
+                    title = os.path.basename(docname)
+            self.titles[docname] = title
+        return title
+
+    def apply(self):
+        env = self.document.settings.env
+
+        # Treat some documents as ecm domain objects.
+        objtype, sep, tail = env.docname.rpartition('/')
+        make_index_entry = _ecm_index_objs.get(objtype)
+        if make_index_entry:
+            title = self.parse_title(env.docname)
+            # Insert the object link target.
+            targetid = '%s:%s' % (objtype, title)
+            targetnode = nodes.target('', '', ids=[targetid])
+            self.document.insert(0, targetnode)
+            # Insert the object index entry.
+            indexnode = addnodes.index()
+            indexnode['entries'] = [make_index_entry(title, targetid)]
+            self.document.insert(0, indexnode)
+            # Add to ecm domain object inventory
+            _ecm_object_inventory(env, self.document, 1, objtype, targetid)
+
+class ECMObject(ObjectDescription):
+
+    def handle_signature(self, sig, signode):
+        # called from sphinx.directives.ObjectDescription.run()
+        signode += addnodes.desc_name(sig, sig)
+        return sig
+
+    def add_target_and_index(self, name, sig, signode):
+        targetid = '%s:%s' % (self.objtype, name)
+        if targetid not in self.state.document.ids:
+            signode['names'].append(targetid)
+            signode['ids'].append(targetid)
+            signode['first'] = (not self.names)
+            self.state.document.note_explicit_target(signode)
+            _ecm_object_inventory(self.env, self.state.document,
+                                    self.lineno, self.objtype, targetid)
+
+        make_index_entry = _ecm_index_objs.get(self.objtype)
+        if make_index_entry:
+            self.indexnode['entries'].append(make_index_entry(name, targetid))
+
+class ECMXRefRole(XRefRole):
+
+    # See sphinx.util.nodes.explicit_title_re; \x00 escapes '<'.
+    _re = re.compile(r'^(.+?)(\s*)(?<!\x00)<(.*?)>$', re.DOTALL)
+    _re_sub = re.compile(r'^([^()\s]+)\s*\(([^()]*)\)$', re.DOTALL)
+
+    def __call__(self, typ, rawtext, text, *args, **keys):
+        # CMake cross-reference targets may contain '<' so escape
+        # any explicit `<target>` with '<' not preceded by whitespace.
+        while True:
+            m = ECMXRefRole._re.match(text)
+            if m and len(m.group(2)) == 0:
+                text = '%s\x00<%s>' % (m.group(1), m.group(3))
+            else:
+                break
+        return XRefRole.__call__(self, typ, rawtext, text, *args, **keys)
+
+class ECMDomain(Domain):
+    """ECM domain."""
+    name = 'ecm'
+    label = 'ECM'
+    object_types = {
+        'module':      ObjType('module',      'module'),
+        'kde-module':  ObjType('kde-module',  'kde-module'),
+        'find-module': ObjType('find-module', 'find-module'),
+        'manual':      ObjType('manual',      'manual'),
+    }
+    directives = {}
+    roles = {
+        'module':      XRefRole(),
+        'kde-module':  XRefRole(),
+        'find-module': XRefRole(),
+        'manual':      XRefRole(),
+    }
+    initial_data = {
+        'objects': {},  # fullname -> docname, objtype
+    }
+
+    def clear_doc(self, docname):
+        for fullname, (fn, _) in self.data['objects'].items():
+            if fn == docname:
+                del self.data['objects'][fullname]
+
+    def resolve_xref(self, env, fromdocname, builder,
+                     typ, target, node, contnode):
+        targetid = '%s:%s' % (typ, target)
+        obj = self.data['objects'].get(targetid)
+        if obj is None:
+            # TODO: warn somehow?
+            return None
+        return make_refnode(builder, fromdocname, obj[0], targetid,
+                            contnode, target)
+
+    def get_objects(self):
+        for refname, (docname, type) in self.data['objects'].iteritems():
+            yield (refname, refname, type, docname, refname, 1)
+
+def setup(app):
+    app.add_directive('ecm-module', ECMModule)
+    app.add_transform(ECMTransform)
+    app.add_domain(ECMDomain)
diff --git a/docs/sphinx/kde-favicon.ico b/docs/sphinx/kde-favicon.ico
new file mode 100644
index 00000000..3741beba
--- /dev/null
+++ b/docs/sphinx/kde-favicon.ico
diff --git a/docs/sphinx/static/ecm.css b/docs/sphinx/static/ecm.css
new file mode 100644
index 00000000..2a326d47
--- /dev/null
+++ b/docs/sphinx/static/ecm.css
@@ -0,0 +1,8 @@
+/* Import the Sphinx theme style.  */
+@import url("default.css");
+
+/* Wrap sidebar content even within words so that long
+   document names do not escape sidebar borders.  */
+div.sphinxsidebarwrapper {
+  word-wrap: break-word;
+}
diff --git a/find-modules/FindEGL.cmake b/find-modules/FindEGL.cmake
index 6237f5cb..765b6692 100644
--- a/find-modules/FindEGL.cmake
+++ b/find-modules/FindEGL.cmake
@@ -1,20 +1,55 @@
-# Try to find EGL on a Unix system
+#.rst:
+# FindEGL
+# -------
 #
-# This will define:
+# Try to find EGL on a Unix system.
 #
-#   EGL_FOUND        - True if EGL is available
-#   EGL_LIBRARIES    - Link these to use EGL
-#   EGL_INCLUDE_DIRS - Include directory for EGL
-#   EGL_DEFINITIONS  - Compiler flags for using EGL
+# This will define the following variables:
 #
-# Additionally, the following imported targets will be defined:
+# ``EGL_FOUND``
+#     True if EGL is available
+# ``EGL_LIBRARIES``
+#     Link these to use EGL
+# ``EGL_INCLUDE_DIRS``
+#     Include directory for EGL
+# ``EGL_DEFINITIONS``
+#     Compiler flags for using EGL
 #
-#   EGL::EGL
+# and the following imported targets:
 #
-# Copyright (c) 2014 Martin Gräßlin <mgraesslin@kde.org>
+# ``EGL::EGL``
+#     The EGL library
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+# In general we recommend using the imported target, as it is easier to use.
+# Bear in mind, however, that if the target is in the link interface of an
+# exported library, it must be made available by the package config file.
+
+#=============================================================================
+# Copyright 2014 Martin Gräßlin <mgraesslin@kde.org>
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. The name of the author may not be used to endorse or promote products
+#    derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#=============================================================================
 
 if(CMAKE_VERSION VERSION_LESS 2.8.12)
     message(FATAL_ERROR "CMake 2.8.12 is required by FindEGL.cmake")
diff --git a/find-modules/FindOpenEXR.cmake b/find-modules/FindOpenEXR.cmake
index 00a2364e..85afebdf 100644
--- a/find-modules/FindOpenEXR.cmake
+++ b/find-modules/FindOpenEXR.cmake
@@ -1,17 +1,32 @@
-# Try to find the OpenEXR libraries
+#.rst:
+# FindOpenEXR
+# -----------
 #
-# This will define:
+# Try to find the OpenEXR libraries.
 #
-#   OpenEXR_FOUND        - True if OpenEXR is available
-#   OpenEXR_LIBRARIES    - Link to these to use OpenEXR
-#   OpenEXR_INCLUDE_DIRS - Include directory for OpenEXR
-#   OpenEXR_DEFINITIONS  - Compiler flags required to link against OpenEXR
-#   OpenEXR::IlmImf      - imported target to link against (instead of using the above variables)
+# This will define the following variables:
 #
+# ``OpenEXR_FOUND``
+#     True if OpenEXR is available
+# ``OpenEXR_LIBRARIES``
+#     Link to these to use OpenEXR
+# ``OpenEXR_INCLUDE_DIRS``
+#     Include directory for OpenEXR
+# ``OpenEXR_DEFINITIONS``
+#     Compiler flags required to link against OpenEXR
+#
+# and the following imported targets:
+#
+# ``OpenEXR::IlmImf``
+#     The OpenEXR core library
+#
+# In general we recommend using the imported target, as it is easier to use.
+# Bear in mind, however, that if the target is in the link interface of an
+# exported library, it must be made available by the package config file.
 
-
-# Copyright (c) 2006, Alexander Neundorf, <neundorf@kde.org>
-# Copyright (c) 2013-2014, Alex Merry, <alex.merry@kdemail.net>
+#=============================================================================
+# Copyright 2013-2014 Alex Merry <alex.merry@kdemail.net>
+# Copyright 2006 Alexander Neundorf <neundorf@kde.org>
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions
@@ -35,6 +50,7 @@
 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 # THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#=============================================================================
 
 
 if(${CMAKE_VERSION} VERSION_LESS 2.8.12)
diff --git a/find-modules/FindSharedMimeInfo.cmake b/find-modules/FindSharedMimeInfo.cmake
index 8dc6f1c4..263a5028 100644
--- a/find-modules/FindSharedMimeInfo.cmake
+++ b/find-modules/FindSharedMimeInfo.cmake
@@ -1,29 +1,56 @@
-# Try to find the shared-mime-info package
+#.rst:
+# FindSharedMimeInfo
+# ------------------
 #
-# This will define
+# Try to find the shared-mime-info package.
 #
-#   SharedMimeInfo_FOUND            - True if system has the shared-mime-info package
-#   UPDATE_MIME_DATABASE_EXECUTABLE - The update-mime-database executable
+# This will define the following variables:
 #
-# In addition, the following targets are defined:
+# ``SharedMimeInfo_FOUND``
+#     True if system has the shared-mime-info package
+# ``UPDATE_MIME_DATABASE_EXECUTABLE``
+#     The update-mime-database executable
 #
-#   SharedMimeInfo::UpdateMimeDatabase
+# and the following imported targets:
 #
-# The follow macro is available:
+# ``SharedMimeInfo::UpdateMimeDatabase``
+#     The update-mime-database executable
 #
-#     update_xdg_mimetypes(path)
+# The follow macro is available::
 #
-# Updates the XDG mime database at install time (unless the DESTDIR environment
-# variable is set, in which case it is up to package managers to perform this
-# task).
+#   update_xdg_mimetypes(<path>)
 #
+# Updates the XDG mime database at install time (unless the ``$DESTDIR``
+# environment variable is set, in which case it is up to package managers to
+# perform this task).
 
-
-# Copyright (c) 2007, Pino Toscano, <toscano.pino@tiscali.it>
-# Copyright (c) 2013-2014, Alex Merry, <alex.merry@kdemail.net>
+#=============================================================================
+# Copyright 2013-2014 Alex Merry <alex.merry@kdemail.net>
+# Copyright 2007 Pino Toscano <toscano.pino@tiscali.it>
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. The name of the author may not be used to endorse or promote products
+#    derived from this software without specific prior written permission.
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#=============================================================================
 
 if(CMAKE_VERSION VERSION_LESS 2.8.12)
     message(FATAL_ERROR "CMake 2.8.12 is required by FindSharedMimeInfo.cmake")
diff --git a/find-modules/FindWayland.cmake b/find-modules/FindWayland.cmake
index c7c599c2..b7790e75 100644
--- a/find-modules/FindWayland.cmake
+++ b/find-modules/FindWayland.cmake
@@ -1,8 +1,12 @@
-# Try to find Wayland on a Unix system
+#.rst:
+# FindWayland
+# -----------
+#
+# Try to find Wayland on a Unix system.
 #
 # This is a component-based find module, which makes use of the COMPONENTS
 # and OPTIONAL_COMPONENTS arguments to find_module.  The following components
-# are available:
+# are available::
 #
 #   Client  Server  Cursor  Egl
 #
@@ -12,33 +16,51 @@
 # This module will define the following variables, independently of the
 # components searched for or found:
 #
-#   Wayland_FOUND      - True if (the requestion version of) Wayland is available
-#   Wayland_VERSION    - Found Wayland version
+# ``Wayland_FOUND``
+#     True if (the requestion version of) Wayland is available
+# ``Wayland_VERSION``
+#     Found Wayland version
 #
-# For each searched-for components, Wayland_<component>_FOUND will be set to true
-# if the corresponding Wayland library was found, and false otherwise.  If
-# Wayland_<component>_FOUND is true, the imported target Wayland::<component> will be
-# defined.  This module will also attempt to determine Wayland_*_VERSION variables
-# for each imported target, although Wayland_VERSION should normally be sufficient.
+# For each searched-for components, ``Wayland_<component>_FOUND`` will be set to
+# true if the corresponding Wayland library was found, and false otherwise.  If
+# ``Wayland_<component>_FOUND`` is true, the imported target
+# ``Wayland::<component>`` will be defined.  This module will also attempt to
+# determine ``Wayland_*_VERSION`` variables for each imported target, although
+# ``Wayland_VERSION`` should normally be sufficient.
 #
 # The following variable will also be defined for convenience, and for
 # compatibility with old-style find module conventions:
 #
-#   Wayland_LIBRARIES  - A list of all Wayland imported targets
+# ``Wayland_LIBRARIES``
+#     A list of all Wayland imported targets
 
 #=============================================================================
-# Copyright 2014 Martin Gräßlin <mgraesslin@kde.org>
 # Copyright 2014 Alex Merry <alex.merry@kde.org>
+# Copyright 2014 Martin Gräßlin <mgraesslin@kde.org>
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
 #
-# Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file COPYING-CMAKE-SCRIPTS for details.
+# 1. Redistributions of source code must retain the copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. The name of the author may not be used to endorse or promote products
+#    derived from this software without specific prior written permission.
 #
-# 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.
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #=============================================================================
-# (To distribute this file outside of extra-cmake-modules, substitute the full
-#  License text for the above reference.)
 
 include(${CMAKE_CURRENT_LIST_DIR}/../modules/ECMFindModuleHelpers.cmake)
 
diff --git a/find-modules/FindX11_XCB.cmake b/find-modules/FindX11_XCB.cmake
index e2c18a99..687a4f3d 100644
--- a/find-modules/FindX11_XCB.cmake
+++ b/find-modules/FindX11_XCB.cmake
@@ -1,17 +1,46 @@
-# - Try to find libX11-xcb
-# Once done this will define
+#.rst:
+# FindX11_XCB
+# -----------
 #
-#  X11_XCB_FOUND       - system has libX11-xcb
-#  X11_XCB_LIBRARIES   - Link these to use libX11-xcb
-#  X11_XCB_INCLUDE_DIR - the libX11-xcb include dir
-#  X11_XCB_DEFINITIONS - compiler switches required for using libX11-xcb
+# This will define the following variables:
+#
+# ``X11_XCB_FOUND``
+#     System has libX11-xcb
+# ``X11_XCB_LIBRARIES``
+#     Link these to use libX11-xcb
+# ``X11_XCB_INCLUDE_DIR``
+#     The libX11-xcb include dir
+# ``X11_XCB_DEFINITIONS``
+#     Compiler switches required for using libX11-xcb
 
-# Copyright (c) 2011 Fredrik Höglund <fredrik@kde.org>
-# Copyright (c) 2008 Helio Chissini de Castro, <helio@kde.org>
-# Copyright (c) 2007 Matthias Kretz, <kretz@kde.org>
+#=============================================================================
+# Copyright 2011 Fredrik Höglund <fredrik@kde.org>
+# Copyright 2008 Helio Chissini de Castro <helio@kde.org>
+# Copyright 2007 Matthias Kretz <kretz@kde.org>
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. The name of the author may not be used to endorse or promote products
+#    derived from this software without specific prior written permission.
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#=============================================================================
 
 IF (NOT WIN32)
   # use pkg-config to get the directories and then use these values
diff --git a/find-modules/FindXCB.cmake b/find-modules/FindXCB.cmake
index a900a624..dd876b21 100644
--- a/find-modules/FindXCB.cmake
+++ b/find-modules/FindXCB.cmake
@@ -1,8 +1,12 @@
-# Try to find XCB on a Unix system
+#.rst:
+# FindXCB
+# -------
 #
-# This is a component-based find module, which makes use of the COMPONENTS
-# and OPTIONAL_COMPONENTS arguments to find_module.  The following components
-# are available:
+# Try to find XCB on a Unix system.
+#
+# This is a component-based find module, which makes use of the COMPONENTS and
+# OPTIONAL_COMPONENTS arguments to find_module.  The following components are
+# available::
 #
 #   XCB
 #   ATOM         AUX          COMPOSITE    CURSOR       DAMAGE
@@ -19,34 +23,52 @@
 # This module will define the following variables, independently of the
 # components searched for or found:
 #
-#   XCB_FOUND      - True if (the requestion version of) xcb is available
-#   XCB_VERSION    - Found xcb version
+# ``XCB_FOUND``
+#     True if (the requestion version of) xcb is available
+# ``XCB_VERSION``
+#     Found xcb version
 #
-# For each searched-for components, XCB_<component>_FOUND will be set to true
-# if the corresponding xcb library was found, and false otherwise.  If
-# XCB_<component>_FOUND is true, the imported target XCB::<component> will be
-# defined.  This module will also attempt to determine XCB_*_VERSION variables
-# for each imported target, although XCB_VERSION should normally be sufficient.
+# For each searched-for components, ``XCB_<component>_FOUND`` will be set to
+# true if the corresponding xcb library was found, and false otherwise.  If
+# ``XCB_<component>_FOUND`` is true, the imported target ``XCB::<component>``
+# will be defined.  This module will also attempt to determine
+# ``XCB_*_VERSION`` variables for each imported target, although
+# ``XCB_VERSION`` should normally be sufficient.
 #
 # The following variable will also be defined for convenience, and for
 # compatibility with old-style find module conventions:
 #
-#   XCB_LIBRARIES  - A list of all XCB imported targets
+# ``XCB_LIBRARIES``
+#     A list of all XCB imported targets
 
 #=============================================================================
 # Copyright 2011 Fredrik Höglund <fredrik@kde.org>
 # Copyright 2013 Martin Gräßlin <mgraesslin@kde.org>
 # Copyright 2014 Alex Merry <alex.merry@kde.org>
 #
-# Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file COPYING-CMAKE-SCRIPTS for details.
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. The name of the author may not be used to endorse or promote products
+#    derived from this software without specific prior written permission.
 #
-# 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.
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #=============================================================================
-# (To distribute this file outside of extra-cmake-modules, substitute the full
-#  License text for the above reference.)
 
 include(${CMAKE_CURRENT_LIST_DIR}/../modules/ECMFindModuleHelpers.cmake)
 
diff --git a/kde-modules/KDECMakeSettings.cmake b/kde-modules/KDECMakeSettings.cmake
index 3f675519..c206ff82 100644
--- a/kde-modules/KDECMakeSettings.cmake
+++ b/kde-modules/KDECMakeSettings.cmake
@@ -1,46 +1,64 @@
-# Change various CMake settings to what the KDE community views as more
+#.rst:
+# KDECMakeSettings
+# ----------------
+#
+# Changes various CMake settings to what the KDE community views as more
 # sensible defaults.
 #
-# It is split into three parts, which can be independently disabled if
-# desired.
+# It is split into three parts, which can be independently disabled if desired.
+#
+# Runtime Paths
+# ~~~~~~~~~~~~~
 #
-# RPATH
+# The default runtime path (used on Unix systems to search for
+# dynamically-linked libraries) is set to include the location that libraries
+# will be installed to (as set in LIB_INSTALL_DIR), and also the linker search
+# path.
 #
-#   The default runtime path (used on Unix systems to search for
-#   dynamically-linked libraries) is set to include the location that
-#   libraries will be installed to (as set in LIB_INSTALL_DIR), and also
-#   the linker search path.
+# Note that ``LIB_INSTALL_DIR`` needs to be set before including this module.
+# Typically, this is done by including the :kde-module:`KDEInstallDirs` module.
 #
-#   Note that LIB_INSTALL_DIR needs to be set before including this
-#   module.  Typically, this is done by including the KDEInstallDirs
-#   module.
+# This section can be disabled by setting ``KDE_SKIP_RPATH_SETTINGS`` to TRUE
+# before including this module.
 #
-#   This section can be disabled by setting
-#     KDE_SKIP_RPATH_SETTINGS
-#   to TRUE before including this module.
 #
+# Testing
+# ~~~~~~~
 #
-# TEST
+# Testing is enabled by default, and an option (BUILD_TESTING) is provided for
+# users to control this. See the CTest module documentation in the CMake manual
+# for more details.
 #
-#   Testing is enabled by default, and an option (BUILD_TESTING) is
-#   provided for users to control this. See the CTest module
-#   documentation in the CMake manual for more details.
+# This section can be disabled by setting ``KDE_SKIP_TEST_SETTINGS`` to TRUE
+# before including this module.
 #
-#   This section can be disabled by setting
-#     KDE_SKIP_TEST_SETTINGS
-#   to TRUE before including this module.
 #
+# Build Settings
+# ~~~~~~~~~~~~~~
 #
-# BUILD
+# Various CMake build defaults are altered, such as searching source and build
+# directories for includes first and enabling automoc by default.
 #
-#   Various CMake build defaults are altered, such as searching source
-#   and build directories for includes first and enabling automoc by
-#   default.
+# This section can be disabled by setting ``KDE_SKIP_BUILD_SETTINGS`` to TRUE
+# before including this module.
+
+#=============================================================================
+# Copyright 2014      Alex Merry <alex.merry@kde.org>
+# Copyright 2013      Aleix Pol <aleixpol@kde.org>
+# Copyright 2012-2013 Stephen Kelly <steveire@gmail.com>
+# Copyright 2007      Matthias Kretz <kretz@kde.org>
+# Copyright 2006-2007 Laurent Montel <montel@kde.org>
+# Copyright 2006-2013 Alex Neundorf <neundorf@kde.org>
 #
-#   This section can be disabled by setting
-#     KDE_SKIP_BUILD_SETTINGS
-#   to TRUE before including this module.
+# 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.)
 
 
 ################# RPATH handling ##################################
diff --git a/kde-modules/KDECompilerSettings.cmake b/kde-modules/KDECompilerSettings.cmake
index d1f9d298..229e4f59 100644
--- a/kde-modules/KDECompilerSettings.cmake
+++ b/kde-modules/KDECompilerSettings.cmake
@@ -1,3 +1,7 @@
+#.rst:
+# KDECompilerSettings
+# -------------------
+#
 # Set useful compile and link flags for C++ (and C) code.
 #
 # Enables many more warnings than the default, and sets stricter modes
@@ -5,25 +9,44 @@
 # kde_target_enable_exceptions() can be used to re-enable them for a
 # specific target.
 #
-#
-# This module provides the following functions:
+# This module provides the following functions::
 #
 #   kde_source_files_enable_exceptions([file1 [file2 [...]]])
 #
 # Enables exceptions for specific source files.  This should not be
 # used on source files in a language other than C++.
 #
+# ::
+#
 #   kde_target_enable_exceptions(target <INTERFACE|PUBLIC|PRIVATE>)
 #
 # Enables exceptions for a specific target.  This should not be used
 # on a target that has source files in a language other than C++.
 #
+# ::
+#
 #   kde_enable_exceptions()
 #
 # Enables exceptions for C++ source files compiled for the
 # CMakeLists.txt file in the current directory and all subdirectories.
-#
 
+#=============================================================================
+# Copyright 2014      Alex Merry <alex.merry@kde.org>
+# Copyright 2013      Stephen Kelly <steveire@gmail.com>
+# Copyright 2012-2013 Raphael Kubo da Costa <rakuco@FreeBSD.org>
+# Copyright 2007      Matthias Kretz <kretz@kde.org>
+# Copyright 2006-2007 Laurent Montel <montel@kde.org>
+# Copyright 2006-2013 Alex Neundorf <neundorf@kde.org>
+#
+# 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.)
 
 ############################################################
 # Toolchain minimal requirements
diff --git a/kde-modules/KDEFrameworkCompilerSettings.cmake b/kde-modules/KDEFrameworkCompilerSettings.cmake
index d0bf4dd7..3b77fc3c 100644
--- a/kde-modules/KDEFrameworkCompilerSettings.cmake
+++ b/kde-modules/KDEFrameworkCompilerSettings.cmake
@@ -1,4 +1,8 @@
-# Set stricter compile and link flags for KDE Frameworks modules
+#.rst:
+# KDEFrameworkCompilerSettings
+# ----------------------------
+#
+# Set stricter compile and link flags for KDE Frameworks modules.
 #
 # The KDECompilerSettings module is included and, in addition, various
 # defines that affect the Qt libraries are set to enforce certain
@@ -7,7 +11,22 @@
 # For example, constructions like QString("foo") are prohibited, instead
 # forcing the use of QLatin1String or QStringLiteral, and some
 # Qt-defined keywords like signals and slots will not be defined.
+
+#=============================================================================
+# Copyright 2013      Albert Astals Cid <aacid@kde.org>
+# Copyright 2007      Matthias Kretz <kretz@kde.org>
+# Copyright 2006-2007 Laurent Montel <montel@kde.org>
+# Copyright 2006-2013 Alex Neundorf <neundorf@kde.org>
+#
+# 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(KDECompilerSettings)
 
diff --git a/kde-modules/KDEInstallDirs.cmake b/kde-modules/KDEInstallDirs.cmake
index 9ff23540..299e919e 100644
--- a/kde-modules/KDEInstallDirs.cmake
+++ b/kde-modules/KDEInstallDirs.cmake
@@ -1,68 +1,122 @@
-# Define KDE standard installation directories
-#
-# Inclusion of this module defines the following variables (default
-# values in parentheses):
-#
-#  BUNDLE_INSTALL_DIR               - (Mac only) application bundles (/Applications/KDE5)
-#  BIN_INSTALL_DIR                  - user executables (bin)
-#  SBIN_INSTALL_DIR                 - system admin executables (sbin)
-#  LIB_INSTALL_DIR                  - object code libraries (lib or lib64 or lib/<multiarch-tuple> on Debian)
-#  LIBEXEC_INSTALL_DIR              - internal executables (${LIB_INSTALL_DIR}/kde5/libexec)
-#  INSTALL_TARGETS_DEFAULT_ARGS     - combines BUNDLE_INSTALL_DIR, BIN_INSTALL_DIR and LIB_INSTALL_DIR; see below
-#
-#  INCLUDE_INSTALL_DIR              - C and C++ header files (include/KF5)
-#
-#  QT_PLUGIN_INSTALL_DIR            - Qt plugins (${LIB_INSTALL_DIR}/plugins)
-#  PLUGIN_INSTALL_DIR               - KDE plugins (${QT_PLUGIN_INSTALL_DIR}/kf5)
-#  IMPORTS_INSTALL_DIR              - QML imports (${QT_PLUGIN_INSTALL_DIR}/imports)
-#  QML_INSTALL_DIR                  - QML2 imports (${LIB_INSTALL_DIR}/qml)
-#
-#  CMAKECONFIG_INSTALL_PREFIX       - CMake configuration files (${LIB_INSTALL_DIR}/cmake)
-#
-#  DATA_INSTALL_DIR                 - read-only architecture-independent data (share)
-#  KCONF_UPDATE_INSTALL_DIR         - kconf_update files (${DATA_INSTALL_DIR}/kconf_update)
-#
-#  DBUS_INTERFACES_INSTALL_DIR      - dbus interfaces (share/dbus-1/interfaces)
-#  DBUS_SERVICES_INSTALL_DIR        - dbus services (share/dbus-1/services)
-#  DBUS_SYSTEM_SERVICES_INSTALL_DIR - dbus system services (share/dbus-1/system-services)
-#  HTML_INSTALL_DIR                 - HTML documentation (share/doc/HTML)
-#  ICON_INSTALL_DIR                 - the icons (share/icons)
-#  KCFG_INSTALL_DIR                 - kconfig files (share/config.kcfg)
-#  LOCALE_INSTALL_DIR               - translations (share/locale)
-#  MAN_INSTALL_DIR                  - man pages (share/man)
-#  SERVICES_INSTALL_DIR             - service (desktop, protocol, ...) files (share/kde5/services)
-#  SERVICETYPES_INSTALL_DIR         - service types desktop files (share/kde5/servicetypes)
-#  SOUND_INSTALL_DIR                - sound files (share/sounds)
-#  TEMPLATES_INSTALL_DIR            - templates (share/templates)
-#  WALLPAPER_INSTALL_DIR            - wallpapers (share/wallpapers)
-#  XDG_APPS_INSTALL_DIR             - application desktop files (share/applications/kde5)
-#  XDG_DIRECTORY_INSTALL_DIR        - XDG directory (share/desktop-directories)
-#  XDG_MIME_INSTALL_DIR             - mimetype XML files (share/mime/packages)
-#
-#  SYSCONF_INSTALL_DIR              - sysconfig files (etc)
-#  CONFIG_INSTALL_DIR               - config files (${SYSCONF_INSTALL_DIR}/xdg)
-#  AUTOSTART_INSTALL_DIR            - autostart files (${CONFIG_INSTALL_DIR}/autostart)
-#
-#  EXEC_INSTALL_PREFIX              - prefix for default values of BIN_INSTALL_DIR, SBIN_INSTALL_DIR and LIB_INSTALL_DIR (empty by default)
-#  SHARE_INSTALL_PREFIX             - replaces "share" in the other variables if set
-#
-# The *_INSTALL_DIR variables may be passed to the DESTINATION options of
-# install() commands for the corresponding file type.  They are set in the CMake
-# cache, and so the defaults above can be overridden by users.
-#
-# Note that these variables do not provide any information about the
-# location of already-installed KDE software.
+#.rst:
+# KDEInstallDirs
+# --------------
+#
+# Define KDE standard installation directories.
+#
+# Inclusion of this module defines the following variables (default values in
+# parentheses):
+#
+# ``BUNDLE_INSTALL_DIR``
+#     (Mac only) application bundles (``/Applications/KDE5``)
+# ``BIN_INSTALL_DIR``
+#     user executables (``bin``)
+# ``SBIN_INSTALL_DIR``
+#     system admin executables (``sbin``)
+# ``LIB_INSTALL_DIR``
+#     object code libraries (``lib or lib64 or lib/<multiarch-tuple> on
+#     Debian``)
+# ``LIBEXEC_INSTALL_DIR``
+#     internal executables (``${LIB_INSTALL_DIR}/kde5/libexec``)
+# ``INSTALL_TARGETS_DEFAULT_ARGS``
+#     combines BUNDLE_INSTALL_DIR, BIN_INSTALL_DIR and LIB_INSTALL_DIR; see
+#     below
+# ``INCLUDE_INSTALL_DIR``
+#     C and C++ header files (``include/KF5``)
+# ``QT_PLUGIN_INSTALL_DIR``
+#     Qt plugins (``${LIB_INSTALL_DIR}/plugins``)
+# ``PLUGIN_INSTALL_DIR``
+#     KDE plugins (``${QT_PLUGIN_INSTALL_DIR}/kf5``)
+# ``IMPORTS_INSTALL_DIR``
+#     QML imports (``${QT_PLUGIN_INSTALL_DIR}/imports``)
+# ``QML_INSTALL_DIR``
+#     QML2 imports (``${LIB_INSTALL_DIR}/qml``)
+# ``CMAKECONFIG_INSTALL_PREFIX``
+#     CMake configuration files (``${LIB_INSTALL_DIR}/cmake``)
+# ``DATA_INSTALL_DIR``
+#     read-only architecture-independent data (``share``)
+# ``KCONF_UPDATE_INSTALL_DIR``
+#     kconf_update files (``${DATA_INSTALL_DIR}/kconf_update``)
+# ``DBUS_INTERFACES_INSTALL_DIR``
+#     dbus interfaces (``share/dbus-1/interfaces``)
+# ``DBUS_SERVICES_INSTALL_DIR``
+#     dbus services (``share/dbus-1/services``)
+# ``DBUS_SYSTEM_SERVICES_INSTALL_DIR``
+#     dbus system services (``share/dbus-1/system-services``)
+# ``HTML_INSTALL_DIR``
+#     HTML documentation (``share/doc/HTML``)
+# ``ICON_INSTALL_DIR``
+#     the icons (``share/icons``)
+# ``KCFG_INSTALL_DIR``
+#     kconfig files (``share/config.kcfg``)
+# ``LOCALE_INSTALL_DIR``
+#     translations (``share/locale``)
+# ``MAN_INSTALL_DIR``
+#     man pages (``share/man``)
+# ``SERVICES_INSTALL_DIR``
+#     service (desktop, protocol, ...) files (``share/kde5/services``)
+# ``SERVICETYPES_INSTALL_DIR``
+#     service types desktop files (``share/kde5/servicetypes``)
+# ``SOUND_INSTALL_DIR``
+#     sound files (``share/sounds``)
+# ``TEMPLATES_INSTALL_DIR``
+#     templates (``share/templates``)
+# ``WALLPAPER_INSTALL_DIR``
+#     wallpapers (``share/wallpapers``)
+# ``XDG_APPS_INSTALL_DIR``
+#     application desktop files (``share/applications/kde5``)
+# ``XDG_DIRECTORY_INSTALL_DIR``
+#     XDG directory (``share/desktop-directories``)
+# ``XDG_MIME_INSTALL_DIR``
+#     mimetype XML files (``share/mime/packages``)
+# ``SYSCONF_INSTALL_DIR``
+#     sysconfig files (``etc``)
+# ``CONFIG_INSTALL_DIR``
+#     config files (``${SYSCONF_INSTALL_DIR}/xdg``)
+# ``AUTOSTART_INSTALL_DIR``
+#     autostart files (``${CONFIG_INSTALL_DIR}/autostart``)
+# ``EXEC_INSTALL_PREFIX``
+#     prefix for default values of BIN_INSTALL_DIR, SBIN_INSTALL_DIR and
+#     LIB_INSTALL_DIR (``empty by default``)
+# ``SHARE_INSTALL_PREFIX``
+#     replaces "share" in the other variables if set
+#
+# The ``*_INSTALL_DIR`` variables may be passed to the DESTINATION options of
+# install() commands for the corresponding file type.  They are set in the
+# CMake cache, and so the defaults above can be overridden by users.
+#
+# Note that these variables do not provide any information about the location of
+# already-installed KDE software.
 #
 # The INSTALL_TARGETS_DEFAULT_ARGS variable should be used when libraries or
 # user-executable applications are installed, in the following manner:
 #
-#    install(TARGETS mylib myapp ${INSTALL_TARGETS_DEFAULT_ARGS})
+# .. code-block:: cmake
+#
+#   install(TARGETS mylib myapp ${INSTALL_TARGETS_DEFAULT_ARGS})
 #
 # It MUST NOT be used for installing plugins, system admin executables or
 # executables only intended for use internally by other code.  Those should use
 # one of the PLUGIN variables, SBIN_INSTALL_DIR or LIBEXEC_INSTALL_DIR
 # respectively.
-#
+
+#=============================================================================
+# Copyright 2014      Alex Merry <alex.merry@kde.org>
+# Copyright 2013      Stephen Kelly <steveire@gmail.com>
+# Copyright 2012      David Faure <faure@kde.org>
+# Copyright 2007      Matthias Kretz <kretz@kde.org>
+# Copyright 2006-2007 Laurent Montel <montel@kde.org>
+# Copyright 2006-2013 Alex Neundorf <neundorf@kde.org>
+#
+# 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.)
 
 
 # Figure out what the default install directory for libraries should be.
diff --git a/modules/ECMAddTests.cmake b/modules/ECMAddTests.cmake
index 67026eca..9052d886 100644
--- a/modules/ECMAddTests.cmake
+++ b/modules/ECMAddTests.cmake
@@ -1,28 +1,50 @@
-include(ECMMarkAsTest)
-include(ECMMarkNonGuiExecutable)
-# This file provides the functions ecm_add_test() and ecm_add_tests().
+#.rst:
+# ECMAddTests
+# -----------
+#
+# Add test executables.
+#
+# ::
+#
+#   ecm_add_test(<sources> LINK_LIBRARIES <library> [<library> [...]]
+#                          [TEST_NAME <name>]
+#                          [NAME_PREFIX <prefix>]
+#                          [GUI])
 #
-# ecm_add_test(<sources> TEST_NAME <name> NAME_PREFIX <prefix> LINK_LIBRARIES <libraries/targets> [GUI])
+# Add a new unit test using the passed source files. The parameter TEST_NAME is
+# used to set the name of the resulting test. It may be omitted if there is
+# exactly one source file. In that case the name of the source file (without the
+# file extension) will be used as the test name.  If the flag GUI is passed the
+# test binary will be a GUI executable, otherwise the resulting binary will be a
+# console application.  The test will be linked against the libraries and/or
+# targets passed to LINK_LIBRARIES.
 #
-# Add a new unit test using the passed source files. The parameter TEST_NAME is used to set the name
-# of the resulting test. It may be omitted if there is exactly one source file. In that case the name of
-# the source file (without the file extension) will be used as the test name.
-# If the flag GUI is passed the test binary will be a GUI executable, otherwise the resulting
-# binary will be a console application.
 #
-# ecm_add_tests(<sources> NAME_PREFIX <prefix> LINK_LIBRARIES <libraries/targets> [GUI])
+# ::
 #
-# Add a new unit test for every source file passed. The name of the tests will be the name of the
-# corresponding source file minus the file extension. If NAME_PREFIX is set, that string will be
-# prepended to each of the unit test names. Each of the unit tests will be linked against the
-# libraries and/or targets passed in the LINK_LIBRARIES parameter.
-# If the flag GUI is passed the test binary will be a GUI executable, otherwise the resulting
-# binary will be a console application.
+#   ecm_add_tests(<sources> LINK_LIBRARIES <library> [<library> [...]]
+#                           [NAME_PREFIX <prefix>]
+#                           [GUI])
 #
-# Copyright (c) 2013, Alexander Richardson, <arichardson.kde@gmail.com>
+# This is a convenient version of ecm_add_test() for when you have many tests
+# that consist of a single source file each.  It behaves like calling
+# ecm_add_test() once for each source file, with the same named arguments.
+
+#=============================================================================
+# Copyright 2013 Alexander Richardson <arichardson.kde@gmail.com>
+#
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+# 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(ECMMarkAsTest)
+include(ECMMarkNonGuiExecutable)
 
 function(ecm_add_test)
   set(options GUI)
diff --git a/modules/ECMCreateQmFromPoFiles.cmake b/modules/ECMCreateQmFromPoFiles.cmake
index f24090b7..92d0d1a8 100644
--- a/modules/ECMCreateQmFromPoFiles.cmake
+++ b/modules/ECMCreateQmFromPoFiles.cmake
@@ -1,12 +1,20 @@
-#  ecm_create_qm_from_po_files(PO_DIR <po_dir>
-#                              POT_NAME <pot_name>
-#                              [DATA_INSTALL_DIR <data_install_dir>]
-#                              [DATA_INSTALL_SUB_DIR <data_install_sub_dir>]
-#                              [CREATE_LOADER <source_file_var>])
+#.rst:
+# ECMCreateQmFromPoFiles
+# ----------------------
 #
-# ecm_create_qm_from_po_files() creates the necessary rules to compile .po
-# files into .qm files, usable by QTranslator. It can also generate a C++ file
-# which takes care of automatically loading those translations.
+# Generate QTranslator (.qm) catalogs from Gettext (.po) catalogs.
+#
+# ::
+#
+#   ecm_create_qm_from_po_files(PO_DIR <po_dir>
+#                               POT_NAME <pot_name>
+#                               [DATA_INSTALL_DIR <data_install_dir>]
+#                               [DATA_INSTALL_SUB_DIR <data_install_sub_dir>]
+#                               [CREATE_LOADER <source_file_var>])
+#
+# Creates the necessary rules to compile .po files into .qm files, usable by
+# QTranslator. It can also generate a C++ file which takes care of automatically
+# loading those translations.
 #
 # PO_DIR is the path to a directory containing .po files.
 #
@@ -18,7 +26,9 @@
 # DATA_INSTALL_DIR defaults to ${DATA_INSTALL_DIR} if defined, otherwise it uses
 # "share". It must point to a directory which is in the list returned by:
 #
-#     QStandardPath::standardLocations(QStandardPath::GenericDataLocation)
+# .. code-block:: cpp
+#
+#   QStandardPath::standardLocations(QStandardPath::GenericDataLocation)
 #
 # otherwise the C++ loader will fail to load the translations.
 #
@@ -33,14 +43,24 @@
 # at startup. The path of the .cpp file is stored in <source_file_var>. This
 # variable must be added to the list of sources to build, like this:
 #
+# .. code-block:: cmake
+#
 #   ecm_create_qm_from_po_files(PO_DIR po POT_NAME mylib CREATE_LOADER myloader)
 #   set(mylib_SRCS foo.cpp bar.cpp ${myloader})
 #   add_library(mylib ${mylib_SRCS})
+
+#=============================================================================
+# Copyright 2014 Aurélien Gâteau <agateau@kde.org>
 #
-# Copyright (c) 2014, Aurélien Gâteau, <agateau@kde.org>
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+# 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.)
 
 # This gives us Qt5::lrelease and Qt5::lupdate but unfortunately no Qt5::lconvert
 # See https://bugreports.qt-project.org/browse/QTBUG-37937
diff --git a/modules/ECMDBusAddActivationService.cmake b/modules/ECMDBusAddActivationService.cmake
index d65be03c..128482e3 100644
--- a/modules/ECMDBusAddActivationService.cmake
+++ b/modules/ECMDBusAddActivationService.cmake
@@ -1,35 +1,48 @@
-# Install a DBus ".service" file, so that a program can be started via DBus activation.
+#.rst:
+# ECMDBusAddActivationService
+# ---------------------------
 #
-# ecm_dbus_add_activation_service(inputfile)
+# Install D-Bus activation .service files.
 #
-# This macro will read the input file, generate a .service file from it, and install it
-# into the right directory for the dbus server to find it.
+# ::
 #
-# Note that in the case of custom install prefixes, the user will have to add the prefix
-# to XDG_DATA_DIRS before starting the DBus server.
+#   ecm_dbus_add_activation_service(<inputfile> [<inputfile> [...]])
+#
+# This macro will configure the input file to generate a .service file, and
+# install it into the right directory for the dbus server to find it.
+#
+# Note that in the case of custom install prefixes, the user will have to add
+# the prefix to XDG_DATA_DIRS before starting the DBus server.
 #
 # Example:
+#
+# .. code-block:: cmake
+#
 #   ecm_dbus_add_activation_service(org.mydomain.myapp.service.in)
 #
-# The file org.mydomain.myapp.service.in contains:
+# The file org.mydomain.myapp.service.in contains::
 #
-# [D-BUS Service]
-# Name=org.mydomain.myapp
-# Exec=@CMAKE_INSTALL_PREFIX@/bin/myapp
+#   [D-BUS Service]
+#   Name=org.mydomain.myapp
+#   Exec=@CMAKE_INSTALL_PREFIX@/bin/myapp
 #
 # This will create and install PREFIX/share/dbus-1/services/org.mydomain.myapp.service
 #
 # See http://techbase.kde.org/Development/Tutorials/D-Bus/Autostart_Services for
 # a more complete documentation.
-#
+
+#=============================================================================
 # Copyright 2012 David Faure <faure@kde.org>
 #
 # Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file Copyright.txt for details.
+# 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.)
 
 macro(ecm_dbus_add_activation_service _sources)
     foreach(_i ${_sources})
@@ -37,6 +50,8 @@ macro(ecm_dbus_add_activation_service _sources)
         string(REGEX REPLACE "\\.service.*$" ".service" _output_file ${_i})
         set(_target ${CMAKE_CURRENT_BINARY_DIR}/${_output_file})
         configure_file(${_service_file} ${_target})
+        # FIXME: document use of ${DBUS_SERVICES_INSTALL_DIR}, and provide a
+        #        fallback
         install(FILES ${_target} DESTINATION ${DBUS_SERVICES_INSTALL_DIR})
     endforeach()
 endmacro()
diff --git a/modules/ECMFindModuleHelpers.cmake b/modules/ECMFindModuleHelpers.cmake
index e38fcaf2..15df9ef0 100644
--- a/modules/ECMFindModuleHelpers.cmake
+++ b/modules/ECMFindModuleHelpers.cmake
@@ -1,13 +1,23 @@
-# Helper macros for find modules
+#.rst:
+# ECMFindModuleHelpers
+# --------------------
+#
+# Helper macros for find modules: ecm_find_package_version_check(),
+# ecm_find_package_parse_components() and
+# ecm_find_package_handle_library_components().
+#
+# ::
 #
 #   ecm_find_package_version_check(<name>)
 #
 # Prints warnings if the CMake version or the project's required CMake version
 # is older than that required by extra-cmake-modules.
 #
+# ::
+#
 #   ecm_find_package_parse_components(<name>
 #       RESULT_VAR <variable>
-#       KNOWN_COMPONENTS <component> [<component>]*
+#       KNOWN_COMPONENTS <component1> [<component2> [...]]
 #       [SKIP_DEPENDENCY_HANDLING])
 #
 # This macro will populate <variable> with a list of components found in
@@ -24,8 +34,10 @@
 # If <component> is listed in <name>_FIND_COMPONENTS, then all its (transitive)
 # dependencies will also be added to <variable>.
 #
+# ::
+#
 #   ecm_find_package_handle_library_components(<name>
-#       COMPONENTS <component> [<component>]*
+#       COMPONENTS <component> [<component> [...]]
 #       [SKIP_DEPENDENCY_HANDLING])
 #       [SKIP_PKG_CONFIG])
 #
@@ -65,6 +77,9 @@
 # the component that is searched for first (note that components are searched
 # for in the order they are passed to the macro).
 
+# FIXME: we should actually set proper traditional variables, because it can
+#        be convenient to use them in the link interface of exported libraries
+
 #=============================================================================
 # Copyright 2014 Alex Merry <alex.merry@kde.org>
 #
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)
 
diff --git a/modules/ECMGeneratePriFile.cmake b/modules/ECMGeneratePriFile.cmake
index d39a9f96..bff2961f 100644
--- a/modules/ECMGeneratePriFile.cmake
+++ b/modules/ECMGeneratePriFile.cmake
@@ -1,33 +1,81 @@
-# This file provides the function ecm_generate_pri_file().
-# ECM_GENERATE_PRI_FILE() creates a .pri file for a library so that qmake-based
-# apps can more easily use the library.
-# It also sets ECM_MKSPECS_INSTALL_DIR as the directory to install the .pri file to.
+#.rst:
+# ECMGeneratePriFile
+# ------------------
 #
-# Requirement: ${PROJECT_VERSION_STRING} must be set before ecm_generate_pri_file.
-# This is usually done by calling ecm_setup_version, which sets it.
+# Generate a ``.pri`` file for the benefit of qmake-based projects.
 #
-# Syntax:
-#   ecm_generate_pri_file(BASE_NAME baseName
-#                         LIB_NAME libName
-#                         [DEPS "dep1 dep2"]
-#                         [FILENAME_VAR filename_variable] )
+# As well as the function below, this module creates the cache variable
+# ``ECM_MKSPECS_INSTALL_DIR`` and sets the default value to ``mkspecs/modules``.
+# This assumes Qt and the current project are both installed to the same
+# non-system prefix.  Packagers who use ``-DCMAKE_INSTALL_PREFIX=/usr`` will
+# certainly want to set ``ECM_MKSPECS_INSTALL_DIR`` to something like
+# ``share/qt5/mkspecs/modules``.
 #
-# * baseName is the name which .pro files will use to refer to the library, i.e. the public name, like KArchive.
-# * libName is the name of the actual library to link to, i.e. the first argument to add_library().
-# * the deps are a space-separated list of base names of other libraries. Use core, widgets, etc. for Qt libs.
-# * filename_variable is the name of a variable, which will be set to contain the path of the .pri file to install
+# The main thing is that this should be the ``modules`` subdirectory of either
+# the default qmake ``mkspecs`` directory or of a directory that will be in the
+# ``$QMAKEPATH`` environment variable when qmake is run.
+#
+# ::
+#
+#   ecm_generate_pri_file(BASE_NAME <baseName>
+#                         LIB_NAME <libName>
+#                         [DEPS "<dep> [<dep> [...]]"]
+#                         [FILENAME_VAR <filename_variable>])
+#
+# If your CMake project produces a Qt-based library, you may expect there to be
+# applications that wish to use it that use a qmake-based build system, rather
+# than a CMake-based one.  Creating a ``.pri`` file will make use of your
+# library convenient for them, in much the same way that CMake config files make
+# things convenient for CMake-based applications.
+#
+# ecm_generate_pri_file() generates just such a file.  It depends on a few
+# variables being set:
+#
+# * ``PROJECT_VERSION_STRING``: typically set by :module:`ECMSetupVersion`,
+#   although the project() command in CMake 3.0.0 and later can also set this.
+# * ``INCLUDE_INSTALL_DIR``: this must be relative to ``CMAKE_INSTALL_PREFIX``,
+#   and includes are assumed to be install in the <baseName> subdirectory.
+# * ``LIB_INSTALL_DIR``: this must be relative to ``CMAKE_INSTALL_PREFIX``.
+#
+# BASE_NAME specifies the name qmake project (.pro) files should use to refer to
+# the library (eg: KArchive).  LIB_NAME is the name of the actual library to
+# link to (ie: the first argument to add_library()).  DEPS is a space-separated
+# list of the base names of other libraries (for Qt libraries, use the same
+# names you use with the ``QT`` variable in a qmake project file, such as "core"
+# for QtCore).  FILENAME_VAR specifies the name of a variable to store the path
+# to the generated file in.
 #
 # Example usage:
-#   ecm_generate_pri_file(BASE_NAME KArchive LIB_NAME KF5KArchive DEPS "core" FILENAME_VAR PRI_FILENAME)
-#   install(FILES ${PRI_FILENAME} DESTINATION ${ECM_MKSPECS_INSTALL_DIR})
 #
-# Copyright (c) 2014, David Faure <faure@kde.org>
+# .. code-block:: cmake
+#
+#   ecm_generate_pri_file(
+#       BASE_NAME KArchive
+#       LIB_NAME KF5KArchive
+#       DEPS "core"
+#       FILENAME_VAR pri_filename
+#   )
+#   install(FILES ${pri_filename} DESTINATION ${ECM_MKSPECS_INSTALL_DIR})
+#
+# A qmake-based project that wished to use this would then do::
+#
+#   QT += KArchive
+#
+# in their ``.pro`` file.
+
+#=============================================================================
+# Copyright 2014 David Faure <faure@kde.org>
+#
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+# 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.)
 
-# This default value makes "installing qt and this lib into the same prefix" work out of the box.
-# Packagers who use -DCMAKE_INSTALL_PREFIX=/usr will certainly want to set ECM_MKSPECS_INSTALL_DIR to something like share/qt5/mkspecs/modules
 set(ECM_MKSPECS_INSTALL_DIR mkspecs/modules CACHE PATH "The directory where mkspecs will be installed to.")
 
 function(ECM_GENERATE_PRI_FILE)
@@ -58,6 +106,8 @@ function(ECM_GENERATE_PRI_FILE)
   set(PRI_TARGET_BASENAME ${EGPF_BASE_NAME})
   set(PRI_TARGET_LIBNAME ${EGPF_LIB_NAME})
   set(PRI_TARGET_QTDEPS ${EGPF_DEPS})
+  # FIXME: Default value for INCLUDE_INSTALL_DIR, argument to override?
+  #        What about absolute paths?
   set(PRI_TARGET_INCLUDES "${CMAKE_INSTALL_PREFIX}/${INCLUDE_INSTALL_DIR}/${PRI_TARGET_BASENAME}")
   set(PRI_TARGET_DEFINES "")
 
@@ -66,6 +116,8 @@ function(ECM_GENERATE_PRI_FILE)
      set(${EGPF_FILENAME_VAR} ${PRI_FILENAME} PARENT_SCOPE)
   endif()
 
+  # FIXME: Default value for LIB_INSTALL_DIR, argument to override?
+  #        What about absolute paths?
   file(GENERATE
      OUTPUT ${PRI_FILENAME}
      CONTENT
diff --git a/modules/ECMInstallIcons.cmake b/modules/ECMInstallIcons.cmake
index e6d2adef..d83003ba 100644
--- a/modules/ECMInstallIcons.cmake
+++ b/modules/ECMInstallIcons.cmake
@@ -1,35 +1,56 @@
-# - Function for installing icons
-# This module provides the function ECM_INSTALL_ICONS().
-
-# ECM_INSTALL_ICONS installs all icons in the current path that
-# match a specific file naming convention into into the directory provided
-# following the Freedesktop.org icon naming spec
-# http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html
-
-# The filenames of the icons in the directory must be in the following format
-# in order to be installed
-# themeSize-Group-name.extension
-
-# The following file extensions are supported
-# .png
-# .mng
-# .svgz
-
-# Where the theme is one of:
-# "hi" for hicolor
-# "lo" for locolor
-# "cr" for the crystal icon theme
-# "ox" for the oxygen icon theme
-
-# Size refers to the size of one dimension of the icon
-# Typically, 16, 22, 32, 48, 64, 128 or 256
-# For svgz files the size should be set to "sc"
-
-# For example the file
-# hi22-action-menu_new.png
-# would be installed into
-# PREFIX/hicolor/22x22/actions/menu_new.png
-
+#.rst:
+# ECMInstallIcons
+# ---------------
+#
+# Installs icons, sorting them into the correct directories according to the
+# FreeDesktop.org icon naming specification.
+#
+# ::
+#
+#   ecm_install_icons(<icon_install_dir> [<l10n_code>])
+#
+# Installs all icons found in ``CMAKE_CURRENT_SOURCE_DIR`` to the correct
+# subdirectory of ``<icon_install_dir>``.  ``<icon_install_dir>`` should
+# typically be something like ``share/icons``, although users of the
+# :kde-module:`KDEInstallDirs` module would normally do
+#
+# .. code-block:: cmake
+#
+#   ecm_install_icons(${ICON_INSTALL_DIR})
+#
+# The icons must be named in the form::
+#
+#   <theme><size>-<group>-<name>.<ext>
+#
+# where ``<theme>`` is one of
+# * ``hi`` for hicolor
+# * ``lo`` for locolor
+# * ``cr`` for the Crystal icon theme
+# * ``ox`` for the Oxygen icon theme
+#
+# ``<size>`` is a numeric pixel size (typically 16, 22, 32, 48, 64, 128 or 256)
+# or ``sc`` for scalable (SVG) files, ``<group>`` is one of the standard
+# FreeDesktop.org icon groups (actions, animations, apps, categories, devices,
+# emblems, emotes, intl, mimetypes, places, status) and ``<ext>`` is one of
+# ``.png``, ``.mng`` or ``.svgz``.
+#
+# For example the file ``hi22-action-menu_new.png`` would be installed into
+# ``<icon_install_dir>/hicolor/22x22/actions/menu_new.png``
+
+#=============================================================================
+# Copyright 2013 David Edmundson <kde@davidedmundson.co.uk>
+# Copyright 2008 Chusslove Illich <caslav.ilic@gmx.net>
+# Copyright 2006 Alex Neundorf <neundorf@kde.org>
+#
+# 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.)
 
 
 # a "map" of short type names to the directories
@@ -47,6 +68,8 @@ set(_ECM_ICON_GROUP_emotes     "emotes")
 set(_ECM_ICON_GROUP_animations "animations")
 set(_ECM_ICON_GROUP_intl       "intl")
 
+# FIXME: this is too KDE-specific; we should keep this map for compatibility,
+#        but get users to specify the full theme name
 # a "map" of short theme names to the theme directory
 set(_ECM_ICON_THEME_ox "oxygen")
 set(_ECM_ICON_THEME_cr "crystalsvg")
@@ -73,6 +96,7 @@ macro (ECM_INSTALL_ICONS _defaultpath )
       set(_group "${CMAKE_MATCH_3}")
       set(_name  "${CMAKE_MATCH_4}")
 
+      # FIXME: don't use map
       set(_theme_GROUP ${_ECM_ICON_THEME_${_type}})
       if( _theme_GROUP)
          _ECM_ADD_ICON_INSTALL_RULE(${CMAKE_CURRENT_BINARY_DIR}/install_icons.cmake
@@ -127,6 +151,7 @@ macro (_ECM_ADD_ICON_INSTALL_RULE _install_SCRIPT _install_PATH _group _orig_NAM
    if (NOT ${_group} STREQUAL ${_install_NAME} )
       set(_icon_GROUP  ${_ECM_ICON_GROUP_${_group}})
       if(NOT _icon_GROUP)
+         # FIXME: print warning if not in map (and not "actions")
          set(_icon_GROUP "actions")
       endif(NOT _icon_GROUP)
 #      message(STATUS "icon: ${_current_ICON} size: ${_size} group: ${_group} name: ${_name} l10n: ${_l10n_SUBDIR}")
@@ -146,4 +171,4 @@ macro (ECM_UPDATE_ICONCACHE)
         file(REMOVE \"${ICON_INSTALL_DIR}/hicolor/temp.txt\")
     endif (NOT DESTDIR_VALUE)
     ")
-endmacro (ECM_UPDATE_ICONCACHE)
\ No newline at end of file
+endmacro (ECM_UPDATE_ICONCACHE)
diff --git a/modules/ECMMarkAsTest.cmake b/modules/ECMMarkAsTest.cmake
index e20bfbfe..24b8cfc7 100644
--- a/modules/ECMMarkAsTest.cmake
+++ b/modules/ECMMarkAsTest.cmake
@@ -1,15 +1,32 @@
-# - Function for marking targets as being only for testing
-# This module provides the function ECM_MARK_AS_TEST().
+#.rst:
+# ECMMarkAsTest
+# -------------
 #
-# The ECM_MARK_AS_TEST function is used to indicate that a target should only
-# be built if the BUILD_TESTING option (provided by CTest) is enabled.
+# Marks a target as only being required for tests.
 #
-# ECM_MARK_AS_TEST( target1 target2 ... targetN )
+# ::
 #
-# If BUILD_TESTING is False, then targets marked as tests are excluded from
-# the ALL target. They are all part of the 'buildtests' target though, so
-# even if building with BUILD_TESTING set to False, it is possible to build
-# all tests by invoking the 'buildtests' target.
+#   ecm_mark_as_test(<target1> [<target2> [...]])
+#
+# This will cause the specified targets to not be built unless either
+# BUILD_TESTING is set to ON or the user invokes the ``buildtests`` target.
+#
+# BUILD_TESTING is created as a cache variable by the CTest module and by the
+# :kde-module:`KDECMakeSettings` module.
+
+#=============================================================================
+# Copyright 2012 Stephen Kelly <steveire@gmail.com>
+# Copyright 2012 Alex Neundorf <neundorf@kde.org>
+#
+# 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.)
 
 if (NOT BUILD_TESTING)
   if(NOT TARGET buildtests)
diff --git a/modules/ECMMarkNonGuiExecutable.cmake b/modules/ECMMarkNonGuiExecutable.cmake
index 3c199ab5..9b680216 100644
--- a/modules/ECMMarkNonGuiExecutable.cmake
+++ b/modules/ECMMarkNonGuiExecutable.cmake
@@ -1,11 +1,29 @@
-# - Function for marking executables as being non-gui
-# This module provides the function ECM_MARK_NONGUI_EXECUTABLE().
+#.rst:
+# ECMMarkNonGuiExecutable
+# -----------------------
 #
-# The ECM_MARK_NONGUI_EXECUTABLE function is used to indicate that an executable
-# target should not be part of a MACOSX_BUNDLE, and should not be a WIN32_EXECUTABLE.
+# Marks an executable target as not being a GUI application.
 #
-# ECM_MARK_NONGUI_EXECUTABLE( target1 target2 ... targetN )
+# ::
 #
+#   ecm_mark_nongui_executable(<target1> [<target2> [...]])
+#
+# This will indicate to CMake that the specified targets should not be included
+# in a MACOSX_BUNDLE and should not be WIN32_EXECUTABLEs.  On platforms other
+# than MacOS X or Windows, this will have no effect.
+
+#=============================================================================
+# Copyright 2012 Stephen Kelly <steveire@gmail.com>
+#
+# 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.)
 
 function(ecm_mark_nongui_executable)
   foreach(_target ${ARGN})
diff --git a/modules/ECMOptionalAddSubdirectory.cmake b/modules/ECMOptionalAddSubdirectory.cmake
index c7931f0c..6cbafa2d 100644
--- a/modules/ECMOptionalAddSubdirectory.cmake
+++ b/modules/ECMOptionalAddSubdirectory.cmake
@@ -1,28 +1,42 @@
-# - ECM_OPTIONAL_ADD_SUBDIRECTORY() combines ADD_SUBDIRECTORY() with an OPTION()
-#
-# ECM_OPTIONAL_ADD_SUBDIRECTORY(<dir>)
-#
-# If you use ECM_OPTIONAL_ADD_SUBDIRECTORY() instead of ADD_SUBDIRECTORY(),
-# this will have two effects
-#
-# 1 - CMake will not complain if the directory doesn't exist
-#     This makes sense if you want to distribute just one of the subdirs
-#     in a source package, e.g. just one of the subdirs in kdeextragear.
-# 2 - If the directory exists, it will offer an option to skip the
-#     subdirectory.
-#     This is useful if you want to compile only a subset of all
-#     directories.
-#
-# If the CMake variable DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to TRUE
-# for the first CMake run on the project, all optional subdirectories will be disabled
-# by default (but can of course be enabled via the respective options).
-# E.g. the following will disable all optional subdirectories except the one named "kcalc":
-#   $ cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_kcalc=TRUE <srcdir>
+#.rst:
+# ECMOptionalAddSubdirectory
+# --------------------------
+#
+# Make subdiretories optional.
+#
+# ::
+#
+#   ecm_optional_add_subdirectory(<dir>)
+#
+# This behaves like add_subdirectory(), except that it does not complain if the
+# directory does not exist.  Additionally, if the directory does exist, it
+# creates an option to allow the user to skip it.
+#
+# This is useful for "meta-projects" that combine several mostly-independent
+# sub-projects.
+#
+# If the CMake variable DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to TRUE for
+# the first CMake run on the project, all optional subdirectories will be
+# disabled by default (but can of course be enabled via the respective options).
+# For example, the following will disable all optional subdirectories except the
+# one named "foo":
+#
+# .. code-block:: sh
+#
+#   cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_foo=TRUE myproject
 
-# Copyright (c) 2007, Alexander Neundorf, <neundorf@kde.org>
+#=============================================================================
+# Copyright 2007 Alexander Neundorf <neundorf@kde.org>
+#
+# Distributed under the OSI-approved BSD License (the "License");
+# see accompanying file COPYING-CMAKE-SCRIPTS for details.
 #
-# Redistribution and use is allowed according to the terms of the BSD license.
-# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+# 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.)
 
 
 function(ECM_OPTIONAL_ADD_SUBDIRECTORY _dir)
diff --git a/modules/ECMPackageConfigHelpers.cmake b/modules/ECMPackageConfigHelpers.cmake
index 2ccf32f6..da65c3ea 100644
--- a/modules/ECMPackageConfigHelpers.cmake
+++ b/modules/ECMPackageConfigHelpers.cmake
@@ -1,11 +1,28 @@
-# - ECM_CONFIGURE_PACKAGE_CONFIG_FILE(), WRITE_BASIC_PACKAGE_VERSION_FILE()
+#.rst:
+# ECMPackageConfigHelpers
+# -----------------------
 #
-# WRITE_BASIC_PACKAGE_VERSION_FILE() is actually just the macro from the
-# CMakePackageConfigHelpers module.
+# Helper macros for generating CMake package config files.
 #
-# ECM_CONFIGURE_PACKAGE_CONFIG_FILE() behaves like
-# CONFIGURE_PACKAGE_CONFIG_FILE() from CMake 2.8.12, except that it adds an
-# extra helper macro: find_dependency().
+# ``write_basic_package_version_file()`` is the same as the one provided by the
+# CMakePackageConfigHelpers module in CMake; see that module's documentation for
+# more information.
+#
+# ::
+#
+#   ecm_configure_package_config_file(<input> <output>
+#       INSTALL_DESTINATION <path>
+#       [PATH_VARS <var1> [<var2> [...]]
+#       [NO_SET_AND_CHECK_MACRO]
+#       [NO_CHECK_REQUIRED_COMPONENTS_MACRO])
+#
+#
+# This behaves in the same way as configure_package_config_file() from CMake
+# 2.8.12, except that it adds an extra helper macro: find_dependency().
+#
+# ::
+#
+#   find_dependency(<dep> [<version> [EXACT]])
 #
 # find_dependency() should be used instead of find_package() to find package
 # dependencies.  It forwards the correct parameters for EXACT, QUIET and
@@ -17,10 +34,23 @@
 # module directly.
 #
 # CMake 3.0.0 will include a CMakeFindDependencyMacro module that will provide
-# the find_dependency macro (which you can include() in your *Config.cmake
+# the find_dependency() macro (which you can include() in your package config
 # file), so this file is only useful for projects whose minimum required version
 # is 2.8.12.
+
+#=============================================================================
+# Copyright 2014 Alex Merry <alex.merry@kdemail.net>
+# Copyright 2013 Stephen Kelly <steveire@gmail.com>
+#
+# 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(${CMAKE_ROOT}/Modules/CMakePackageConfigHelpers.cmake)
 
diff --git a/modules/ECMSetupVersion.cmake b/modules/ECMSetupVersion.cmake
index 3a8defd8..3ae6fa8f 100644
--- a/modules/ECMSetupVersion.cmake
+++ b/modules/ECMSetupVersion.cmake
@@ -1,49 +1,70 @@
-# This file provides the function ecm_setup_version().
-# ECM_SETUP_VERSION() bundles three things which are usually done for versioned libraries:
-#  - it sets a set of version variables
-#  - optionally it creates a C version header file, which can then be installed along with the library
-#  - optionally it creates a CMake package version file, which can then be installed along with a
-#    CMake package Config.cmake file
+#.rst:
+# ECMSetupVersion
+# ---------------
+#
+# Handle library version information.
+#
+# ::
 #
 #   ecm_setup_version(<version>
-#                     VARIABLE_PREFIX prefix
+#                     VARIABLE_PREFIX <prefix>
 #                     [SOVERSION <soversion>]
-#                     [VERSION_HEADER filename]
-#                     [PACKAGE_VERSION_FILE filename] )
+#                     [VERSION_HEADER <filename>]
+#                     [PACKAGE_VERSION_FILE <filename>] )
+#
+# This parses a version string and sets up a standard set of version variables.
+# It can optionally also create a C version header file and a CMake package
+# version file to install along with the library.
 #
+# If the ``<version>`` argument is of the form ``<major>.<minor>.<patch>``
+# (or ``<major>.<minor>.<patch>.<tweak>``), The following CMake variables are
+# set::
 #
-# ecm_setup_version() sets the following CMake variables
-#    <prefix>_VERSION_MAJOR = <version_major_component>
-#    <prefix>_VERSION_MINOR = <version_minor_component>
-#    <prefix>_VERSION_PATCH = <version_patch_component>
-#    <prefix>_VERSION_STRING = <major>.<minor>.<patch>
-#    <prefix>_SOVERSION is set to <major> if <soversion> has not been specified.
+#   <prefix>_VERSION_MAJOR  - <major>
+#   <prefix>_VERSION_MINOR  - <minor>
+#   <prefix>_VERSION_PATCH  - <patch>
+#   <prefix>_VERSION_STRING - <version>
+#   <prefix>_SOVERSION      - <soversion>, or <major> if SOVERSION was not given
+#   PROJECT_VERSION_MAJOR   - <major>
+#   PROJECT_VERSION_MINOR   - <minor>
+#   PROJECT_VERSION_PATCH   - <patch>
+#   PROJECT_VERSION_STRING  - <version>
 #
-# It also sets PROJECT_VERSION_MAJOR, PROJECT_VERSION_MINOR, PROJECT_VERSION_PATCH and
-# PROJECT_VERSION_STRING, for easier use with configure_file and file(GENERATE).
+# If the VERSION_HEADER option is used, a simple C header is generated with the
+# given filename. If filename is a relative path, it is interpreted as relative
+# to CMAKE_CURRENT_BINARY_DIR.  The generated header contains the following
+# macros::
 #
-# If the VERSION_HEADER option is used, a simple C header is generated with the given
-# filename. If filename is a relative path, it is interpreted as relative to
-# CMAKE_CURRENT_BINARY_DIR.
-# The generated header contains the following macros:
-#    <prefix>_VERSION_MAJOR
-#    <prefix>_VERSION_MINOR
-#    <prefix>_VERSION_PATCH
-#    <prefix>_VERSION_STRING - containing the full version number as a C string
-#    <prefix>_VERSION - containing the full version combined into one integer
+#    <prefix>_VERSION_MAJOR  - <major> as an integer
+#    <prefix>_VERSION_MINOR  - <minor> as an integer
+#    <prefix>_VERSION_PATCH  - <patch> as an integer
+#    <prefix>_VERSION_STRING - <version> as a C string
+#    <prefix>_VERSION        - the version as an integer
+#
+# ``<prefix>_VERSION`` has ``<patch>`` in the bottom 8 bits, ``<minor>`` in the
+# next 8 bits and ``<major>`` in the remaining bits.  Note that ``<patch>`` and
+# ``<minor>`` must be less than 256.
 #
 # If the PACKAGE_VERSION_FILE option is used, a simple CMake package version
-# file is created using the write_basic_package_version_file() macro coming
-# with CMake. It should be installed along the Config.cmake file of the library
-# into the same directory where it can be found by find_package().
-# Also here, if the given filename is a relative path, it is interpreted as
-# relative to CMAKE_CURRENT_BINARY_DIR.
+# file is created using the write_basic_package_version_file() macro provided by
+# CMake. It should be installed in the same location as the Config.cmake file of
+# the library so that it can be found by find_package().  If the filename is a
+# relative path, it is interpreted as relative to CMAKE_CURRENT_BINARY_DIR.
 
-# Copyright (c) 2012, Alexander Neundorf, <neundorf@kde.org>
+#=============================================================================
+# Copyright 2012 Alexander Neundorf <neundorf@kde.org>
 #
-# 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.)
+
+# FIXME: Figure out how this should interact with CMP0048 in CMake 3.0.0
 
 include(CMakePackageConfigHelpers)
 
diff --git a/modules/ECMUseFindModules.cmake b/modules/ECMUseFindModules.cmake
index 6bf3c904..25f42666 100644
--- a/modules/ECMUseFindModules.cmake
+++ b/modules/ECMUseFindModules.cmake
@@ -1,40 +1,62 @@
-# - Selectively use some of the Find-modules provided by extra-cmake-modules (ECM)
+#.rst:
+# ECMUseFindModules
+# -----------------
 #
-# ECM_USE_FIND_MODULES(DIR <dir> MODULES module1.cmake module2.cmake .. moduleN.cmake [NO_OVERRIDE] )
+# Selectively use some of the find modules provided by extra-cmake-modules.
 #
-# This macro is automatically available once extra-cmake-modules has been found, so it is not
-# necessary to include(ECMUseFindModules) explicitly.
+# This module is automatically available once extra-cmake-modules has been
+# found, so it is not necessary to ``include(ECMUseFindModules)`` explicitly.
 #
-# Use this macro instead of simply adding ${ECM_FIND_MODULE_DIR} to CMAKE_MODULE_PATH
-# if you want to use only a subset or some specific find-modules coming with extra-cmake-modules.
-# The given find-modules will be copied to the given directory. This directory should then be added
-# to CMAKE_MODULE_PATH. The given modules override modules of the same name coming with CMake, except
-# if the NO_OVERRIDE option has been used.
+# ::
 #
-#   DIR <dir> : the selected module files will be copied to that directory. The directory should be
-#               located somewhere inside ${CMAKE_BINARY_DIR}. It should then be added to CMAKE_MODULE_PATH .
-#               The directory is created if it does not exist yet.
-#   MODULES   : the list of find-modules to be used from extra-cmake-modules
-#   NO_OVERRIDE: if used, the given modules will only be used if they do not exist in the currently used
-#                CMake version
+#   ecm_use_find_modules(DIR <dir>
+#                        MODULES module1.cmake [module2.cmake [...]]
+#                        [NO_OVERRIDE])
+#
+# This allows selective use of the find modules provided by ECM, including
+# deferring to CMake's versions of those modules if it has them.  Rather than
+# adding ``${ECM_FIND_MODULE_DIR}`` to ``CMAKE_MODULE_PATH``, you use
+# ecm_use_find_modules() to copy the modules you want to a local (build)
+# directory, and add that to ``CMAKE_MODULE_PATH``.
+#
+# The find modules given to MODULES will be copied to the directory given by DIR
+# (which should be located in ``${CMAKE_BINARY_DIR}`` and added to
+# ``CMAKE_MODULE_PATH``).  If NO_OVERRIDE is given, only modules not also
+# provided by CMake will be copied.
 #
 # Example:
-#   find_package(ECM 0.0.4 REQUIRED)
-#   ecm_use_find_modules(DIR ${CMAKE_BINARY_DIR}/cmake/ Modules FindBlueZ.cmake NO_OVERRIDE )
-#   set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake/ )
 #
-# This example will make FindBlueZ.cmake available in your project, but only as long as it
-# is not yet part of CMake. The file will be copied into ${CMAKE_BINARY_DIR}/cmake/, and then this
-# directory is added to CMAKE_MODULE_PATH.
+# .. code-block:: cmake
+#
+#   find_package(ECM REQUIRED)
+#   ecm_use_find_modules(
+#       DIR ${CMAKE_BINARY_DIR}/cmake
+#       MODULES FindEGL.cmake
+#       NO_OVERRIDE
+#   )
+#   set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake)
+#
+# This example will make ``FindEGL.cmake`` available in your project, but only
+# as long as it is not yet part of CMake. Calls to ``find_package(EGL)`` will
+# then make use of this copied module (or the CMake module if it exists).
+#
+# Another possible use for this macro is to take copies of find modules that can
+# be installed along with config files if they are required as a dependency (for
+# example, if targets provided by the find module are in the link interface of a
+# library).
 
+#=============================================================================
 # Copyright 2011 Alexander Neundorf <neundorf@kde.org>
 #
 # Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file Copyright.txt for details.
+# 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)