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

1 files changed, 130 insertions, 130 deletions

diff --git a/toolchain/Android.cmake b/toolchain/Android.cmake
index db70de50..3f2443c6 100644
--- a/toolchain/Android.cmake
+++ b/toolchain/Android.cmake
@@ -1,137 +1,137 @@
-#.rst:
-# AndroidToolchain
-# ----------------
-#
-# Enable easy compilation of cmake projects on Android.
-#
-# By using this android toolchain, the projects will be set up to compile the
-# specified project targeting an Android platform, depending on its input.
-# Furthermore, if desired, an APK can be directly generated by using the
-# `androiddeployqt <https://doc.qt.io/qt-5/deployment-android.html>`_ tool.
-#
-# CMake upstream has Android support now. This module will still give us some
-# useful features offering androiddeployqt integration and adequate executables
-# format for our Android applications.
-#
-# Since we are using CMake Android support, any information from CMake documentation
-# still applies:
-# https://cmake.org/cmake/help/v3.7/manual/cmake-toolchains.7.html#cross-compiling-for-android
-#
-# .. note::
-#
-#   This module requires CMake 3.18.
-#
-# Since 1.7.0.
-#
-# Usage
-# =====
-#
-# To use this file, you need to set the ``CMAKE_TOOLCHAIN_FILE`` to point to
-# ``Android.cmake`` on the command line::
-#
-#   cmake -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake
-#
-# You will also need to provide the locations of the Android NDK and SDK. This
-# can be done on the commandline or with environment variables; in either case
-# the variable names are:
-#
-# ``CMAKE_ANDROID_NDK``
-#     The NDK root path.
-# ``ANDROID_SDK_ROOT``
-#     The SDK root path.
-#
-# Additional options are specified as cache variables (eg: on the command line):
-#
-# ``ANDROID_ABI``
-#     The ABI to use. See the ``sources/cxx-stl/gnu-libstdc++/*/libs``
-#     directories in the NDK. Default: ``armeabi-v7a``.
-# ``ANDROID_SDK_COMPILE_API``
-#     The platform API level to compile against. May be different from the NDK
-#     target. Default: newest installed version (e.g. android-30).
-# ``ANDROID_SDK_BUILD_TOOLS_REVISION``
-#     The build tools version to use.
-#     Default: newest installed version (e.g. ``30.0.2``).
-# ``ANDROID_EXTRA_LIBS``
-#     The ";"-separated list of full paths to libs to include in resulting APK.
-#
-# For integrating other libraries which are not part of the Android toolchain,
-# like Qt5, and installed to a separate prefix on the host system, the install
-# prefixes of those libraries would be passed as alternative roots as list via
-# ``ECM_ADDITIONAL_FIND_ROOT_PATH``. Since 5.30.0.
-#
-# For example, for integrating a Qt5 for Android present at
-# ``~/Qt/5.14.2/android/`` and some other libraries installed to
-# the prefix ``/opt/android/foo``, you would use::
-#
-#   cmake \
-#     -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake \
-#     -DECM_ADDITIONAL_FIND_ROOT_PATH="~/Qt/5.14.2/android/;/opt/android/foo"
-#
-# If your project uses ``find_package()`` to locate build tools on the host
-# system, make sure to pass ``CMAKE_FIND_ROOT_PATH_BOTH`` or
-# ``NO_CMAKE_FIND_ROOT_PATH`` as argument in the call. See the
-# ``find_package()`` documentation for more details.
-#
-# Deploying Qt Applications
-# =========================
-#
-# After building the application, you will need to generate an APK that can be
-# deployed to an Android device. This module integrates androiddeployqt support
-# to help with this for Qt-based projects. To enable this, set the
-# ``QTANDROID_EXPORTED_TARGET`` variable to the targets you wish to export as an
-# APK (in a ;-separed list), as well as ``ANDROID_APK_DIR`` to a directory
-# containing some basic information. This will create a ``create-apk-<target>``
-# target that will generate the APK file.  See the `Qt on Android deployment
-# documentation <https://doc.qt.io/qt-5/deployment-android.html>`_ for more
-# information.
-#
-# For example, you could do::
-#
-#   cmake \
-#     -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake \
-#     -DQTANDROID_EXPORTED_TARGET=myapp \
-#     -DANDROID_APK_DIR=myapp-apk
-#   make
-#   make create-apk-myapp
-#
-# You can specify the APK output directory by setting ``ANDROID_APK_OUTPUT_DIR``.
-# Otherwise the APK can be found in ``myapp_build_apk/`` in the build directory.
-#
-# The create-apk-myapp target will be able to take an ARGS parameter with further
-# arguments for androiddeployqt. For example, one can use::
-#
-#   make create-apk-myapp ARGS="--install"
-#
-# To install the apk to test. To generate a signed apk, one can do it with the
-# following syntax::
-#
-#   make create-apk-myapp ARGS="--sign ~/my.keystore alias_name"
-#
-# In case it's needed for your application to set the APK directory from cmake
-# scripting you can also set the directory as the ANDROID_APK_DIR property of
-# the create-apk-myapp target.
-#
-# See Android documentation on how to create a keystore to use
-#
-# Advanced Options
-# ================
-#
-# The following packaging options are mainly interesting for automation or integration
-# with CI/CD pipelines:
-# ``ANDROID_APK_OUTPUT_DIR``
-#     Specifies a folder where the generated APK files should be placed.
-# ``ANDROID_FASTLANE_METADATA_OUTPUT_DIR``
-#     Specifies a folder where the generated metadata for the F-Droid store
-#     should be placed.
-# ``ANDROIDDEPLOYQT_EXTRA_ARGS``
-#     Allows to pass additional arguments to `androiddeployqt`. This is an alternative to
-#     the `ARGS=` argument for `make` and unlike that works with all CMake generators.
-
-# =============================================================================
 # SPDX-FileCopyrightText: 2014 Aleix Pol i Gonzalez <aleixpol@kde.org>
 #
 # SPDX-License-Identifier: BSD-3-Clause
 
+#[=======================================================================[.rst:
+AndroidToolchain
+----------------
+
+Enable easy compilation of cmake projects on Android.
+
+By using this android toolchain, the projects will be set up to compile the
+specified project targeting an Android platform, depending on its input.
+Furthermore, if desired, an APK can be directly generated by using the
+`androiddeployqt <https://doc.qt.io/qt-5/deployment-android.html>`_ tool.
+
+CMake upstream has Android support now. This module will still give us some
+useful features offering androiddeployqt integration and adequate executables
+format for our Android applications.
+
+Since we are using CMake Android support, any information from CMake documentation
+still applies:
+https://cmake.org/cmake/help/v3.7/manual/cmake-toolchains.7.html#cross-compiling-for-android
+
+.. note::
+
+  This module requires CMake 3.18.
+
+Since 1.7.0.
+
+Usage
+=====
+
+To use this file, you need to set the ``CMAKE_TOOLCHAIN_FILE`` to point to
+``Android.cmake`` on the command line::
+
+  cmake -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake
+
+You will also need to provide the locations of the Android NDK and SDK. This
+can be done on the commandline or with environment variables; in either case
+the variable names are:
+
+``CMAKE_ANDROID_NDK``
+    The NDK root path.
+``ANDROID_SDK_ROOT``
+    The SDK root path.
+
+Additional options are specified as cache variables (eg: on the command line):
+
+``ANDROID_ABI``
+    The ABI to use. See the ``sources/cxx-stl/gnu-libstdc++/*/libs``
+    directories in the NDK. Default: ``armeabi-v7a``.
+``ANDROID_SDK_COMPILE_API``
+    The platform API level to compile against. May be different from the NDK
+    target. Default: newest installed version (e.g. android-30).
+``ANDROID_SDK_BUILD_TOOLS_REVISION``
+    The build tools version to use.
+    Default: newest installed version (e.g. ``30.0.2``).
+``ANDROID_EXTRA_LIBS``
+    The ";"-separated list of full paths to libs to include in resulting APK.
+
+For integrating other libraries which are not part of the Android toolchain,
+like Qt5, and installed to a separate prefix on the host system, the install
+prefixes of those libraries would be passed as alternative roots as list via
+``ECM_ADDITIONAL_FIND_ROOT_PATH``. Since 5.30.0.
+
+For example, for integrating a Qt5 for Android present at
+``~/Qt/5.14.2/android/`` and some other libraries installed to
+the prefix ``/opt/android/foo``, you would use::
+
+  cmake \
+    -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake \
+    -DECM_ADDITIONAL_FIND_ROOT_PATH="~/Qt/5.14.2/android/;/opt/android/foo"
+
+If your project uses ``find_package()`` to locate build tools on the host
+system, make sure to pass ``CMAKE_FIND_ROOT_PATH_BOTH`` or
+``NO_CMAKE_FIND_ROOT_PATH`` as argument in the call. See the
+``find_package()`` documentation for more details.
+
+Deploying Qt Applications
+=========================
+
+After building the application, you will need to generate an APK that can be
+deployed to an Android device. This module integrates androiddeployqt support
+to help with this for Qt-based projects. To enable this, set the
+``QTANDROID_EXPORTED_TARGET`` variable to the targets you wish to export as an
+APK (in a ;-separed list), as well as ``ANDROID_APK_DIR`` to a directory
+containing some basic information. This will create a ``create-apk-<target>``
+target that will generate the APK file.  See the `Qt on Android deployment
+documentation <https://doc.qt.io/qt-5/deployment-android.html>`_ for more
+information.
+
+For example, you could do::
+
+  cmake \
+    -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake \
+    -DQTANDROID_EXPORTED_TARGET=myapp \
+    -DANDROID_APK_DIR=myapp-apk
+  make
+  make create-apk-myapp
+
+You can specify the APK output directory by setting ``ANDROID_APK_OUTPUT_DIR``.
+Otherwise the APK can be found in ``myapp_build_apk/`` in the build directory.
+
+The create-apk-myapp target will be able to take an ARGS parameter with further
+arguments for androiddeployqt. For example, one can use::
+
+  make create-apk-myapp ARGS="--install"
+
+To install the apk to test. To generate a signed apk, one can do it with the
+following syntax::
+
+  make create-apk-myapp ARGS="--sign ~/my.keystore alias_name"
+
+In case it's needed for your application to set the APK directory from cmake
+scripting you can also set the directory as the ANDROID_APK_DIR property of
+the create-apk-myapp target.
+
+See Android documentation on how to create a keystore to use
+
+Advanced Options
+================
+
+The following packaging options are mainly interesting for automation or integration
+with CI/CD pipelines:
+``ANDROID_APK_OUTPUT_DIR``
+    Specifies a folder where the generated APK files should be placed.
+``ANDROID_FASTLANE_METADATA_OUTPUT_DIR``
+    Specifies a folder where the generated metadata for the F-Droid store
+    should be placed.
+``ANDROIDDEPLOYQT_EXTRA_ARGS``
+    Allows to pass additional arguments to `androiddeployqt`. This is an alternative to
+    the `ARGS=` argument for `make` and unlike that works with all CMake generators.
+#]=======================================================================]
+
 cmake_minimum_required(VERSION "3.18")
 
 macro(set_deprecated_variable actual_variable deprecated_variable default_value)