Modules docs: move rst docs into bracket comments

CMake >= 3.0 supports bracket comments, and the reStructuredText
integration code in sphinx/ext/ecm.py already supports extracting
the docs from a bracket comment instead.
Editing documentation without leading line comment markers is more simple,
e,g. when reflowing text over lines.

With ECM meanwhile requiring CMake 3.5 now it is possible to switch
(and thus follow also the approach used by cmake itself).

NO_CHANGELOG

2 files changed, 54 insertions, 56 deletions

diff --git a/cmake/FindQCollectionGenerator.cmake b/cmake/FindQCollectionGenerator.cmake
index b7ff0c83..c350dae8 100644
--- a/cmake/FindQCollectionGenerator.cmake
+++ b/cmake/FindQCollectionGenerator.cmake
@@ -1,36 +1,35 @@
-#.rst:
-# FindQCollectionGenerator
-# ------------------------
-#
-# Try to find the Qt help collection generator.
-#
-# This will define the following variables:
-#
-# ``QCollectionGenerator_FOUND``
-#     True if (the requested version of) Sphinx is available
-# ``QCollectionGenerator_VERSION``
-#     The version of the Qt help collection generator. Note that this not the
-#     same as the version of Qt it is provided by.
-# ``QCollectionGenerator_QT_VERSION``
-#     The version of Qt that the Qt help collection generator is from.
-# ``QCollectionGenerator_EXECUTABLE``
-#     The path to the Qt help collection generator executable.
-#
-# If ``QCollectionGenerator_FOUND`` is TRUE, it will also define the following
-# imported target:
-#
-# ``QCollectionGenerator::Generator``
-#     The Qt help collection generator.
-#
-# In general we recommend using the imported target, as it is easier to use.
-#
-# Since 5.17.0.
-
-#=============================================================================
 # SPDX-FileCopyrightText: 2015 Alex Merry <alex.merry@kde.org>
 #
 # SPDX-License-Identifier: BSD-3-Clause
-#=============================================================================
+
+#[=======================================================================[.rst:
+FindQCollectionGenerator
+------------------------
+
+Try to find the Qt help collection generator.
+
+This will define the following variables:
+
+``QCollectionGenerator_FOUND``
+    True if (the requested version of) Sphinx is available
+``QCollectionGenerator_VERSION``
+    The version of the Qt help collection generator. Note that this not the
+    same as the version of Qt it is provided by.
+``QCollectionGenerator_QT_VERSION``
+    The version of Qt that the Qt help collection generator is from.
+``QCollectionGenerator_EXECUTABLE``
+    The path to the Qt help collection generator executable.
+
+If ``QCollectionGenerator_FOUND`` is TRUE, it will also define the following
+imported target:
+
+``QCollectionGenerator::Generator``
+    The Qt help collection generator.
+
+In general we recommend using the imported target, as it is easier to use.
+
+Since 5.17.0.
+#]=======================================================================]
 
 find_program(QCollectionGenerator_EXECUTABLE
     NAMES
diff --git a/cmake/FindSphinx.cmake b/cmake/FindSphinx.cmake
index dc83ec6d..a25a8e10 100644
--- a/cmake/FindSphinx.cmake
+++ b/cmake/FindSphinx.cmake
@@ -1,32 +1,31 @@
-#.rst:
-# FindSphinx
-# ----------
-#
-# Try to find the Sphinx documentation builder.
-#
-# This will define the following variables:
-#
-# ``Sphinx_FOUND``
-#     True if (the requested version of) Sphinx is available
-# ``Sphinx_VERSION``
-#     The version of the Sphinx documentation builder.
-# ``Sphinx_BUILD_EXECUTABLE``
-#     The path to the Sphinx documentation builder executable.
-#
-# If ``Sphinx_FOUND`` is TRUE, it will also define the following imported target:
-#
-# ``Sphinx::Build``
-#     The Sphinx documentation builder.
-#
-# In general we recommend using the imported target, as it is easier to use.
-#
-# Since 5.17.0.
-
-#=============================================================================
 # SPDX-FileCopyrightText: 2015 Alex Merry <alex.merry@kde.org>
 #
 # SPDX-License-Identifier: BSD-3-Clause
-#=============================================================================
+
+#[=======================================================================[.rst:
+FindSphinx
+----------
+
+Try to find the Sphinx documentation builder.
+
+This will define the following variables:
+
+``Sphinx_FOUND``
+    True if (the requested version of) Sphinx is available
+``Sphinx_VERSION``
+    The version of the Sphinx documentation builder.
+``Sphinx_BUILD_EXECUTABLE``
+    The path to the Sphinx documentation builder executable.
+
+If ``Sphinx_FOUND`` is TRUE, it will also define the following imported target:
+
+``Sphinx::Build``
+    The Sphinx documentation builder.
+
+In general we recommend using the imported target, as it is easier to use.
+
+Since 5.17.0.
+#]=======================================================================]
 
 # Distros sometimes rename Python executables to allow for parallel
 # installation of Python2 and Python3 versions