CTest: Document target names reserved for the dashboard

Help/manual/cmake-buildsystem.7.rst

@@ -63,6 +63,9 @@ project-wide convenience targets.
   ``ZERO_CHECK`` are always reserved.
 * Some modules reserve additional names: e.g., ``test`` when :module:`CTest`
   is enabled, and ``package`` when :module:`CPack` is enabled.
+  The :module:`CTest` module also reserves the names of its
+  :ref:`dashboard targets <CTest Dashboard Targets>`, such as
+  ``Experimental`` and ``NightlyTest``.
 * Generators may also create their own convenience targets, such as
   ``install/parallel`` with the :ref:`Ninja Generators`.  See the
   :manual:`cmake-generators(7)` manual for the target names documented by

Modules/CTest.cmake

@@ -58,6 +58,49 @@ the :variable:`CTEST_USE_LAUNCHERS` variable:
   set(CTEST_USE_LAUNCHERS 1)
 
 in the ``CTestConfig.cmake`` file.
+
+.. _`CTest Dashboard Targets`:
+
+Dashboard Targets
+^^^^^^^^^^^^^^^^^
+
+When :variable:`BUILD_TESTING` is enabled, the module also adds custom
+targets to the build system that run a :ref:`Dashboard Client` from the
+build tree and submit the results.  Each target runs :option:`ctest -S`
+on a script generated by the module in ``CMakeFiles/CTestScript.cmake``.
+The script is configured with the settings collected by the module.
+
+The following targets are added for all generators:
+
+``Experimental``
+  Run the ``Start``, ``Configure``, ``Build``, ``Test``, ``Coverage``,
+  and ``Submit`` steps in ``Experimental`` mode.
+
+``Nightly``
+  Run the ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``,
+  ``Coverage``, and ``Submit`` steps in ``Nightly`` mode.
+
+``Continuous``
+  Run the same steps as ``Nightly`` in ``Continuous`` mode, but stop
+  after the ``Update`` step if it reports no changes.
+
+``NightlyMemoryCheck``
+  Run the ``Start``, ``Update``, ``Configure``, ``Build``, ``MemCheck``,
+  ``Coverage``, and ``Submit`` steps in ``Nightly`` mode.
+
+The :ref:`Makefile Generators`, :ref:`Ninja Generators`, and
+:generator:`FASTBuild` generator also add a ``<Mode><Step>`` target
+for each combination of ``<Mode>`` in ``Experimental``, ``Nightly``,
+and ``Continuous`` and ``<Step>`` in ``Start``, ``Update``,
+``Configure``, ``Build``, ``Test``, ``Coverage``, ``MemCheck``, and
+``Submit``.  Each runs only that step, such as:
+
+.. code-block:: shell
+
+  cmake --build . --target ExperimentalTest
+
+See the :ref:`Dashboard Client` documentation for details on each
+step and mode.
 #]=======================================================================]
 
 option(BUILD_TESTING "Build the testing tree." ON)