Merge topic 'doc-CTEST_USE_LAUNCHERS-ninja'

7244e845 ctest: Consolidate documentation of CTEST_USE_LAUNCHERS (#15533)
f693c136 Modules/CTest: Improve documentation formatting
5cbedd6b Modules/CTest: Use bracket comment for documentation block

2 files changed, 54 insertions, 67 deletions

diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst
index d0ac28d..c91321b 100644
--- a/Help/manual/ctest.1.rst
+++ b/Help/manual/ctest.1.rst
@@ -372,6 +372,8 @@ Options
 
 .. include:: OPTIONS_HELP.txt
 
+.. _`Dashboard Client`:
+
 Dashboard Client
 ================
 
@@ -749,8 +751,9 @@ Configuration settings include:
     initialized by the :command:`build_command` command
 
 ``UseLaunchers``
-  For build trees generated by CMake using a Makefile generator
-  or the :generator:`Ninja` generator, specify whether the
+  For build trees generated by CMake using one of the
+  :ref:`Makefile Generators` or the :generator:`Ninja`
+  generator, specify whether the
   ``CTEST_USE_LAUNCHERS`` feature is enabled by the
   :module:`CTestUseLaunchers` module (also included by the
   :module:`CTest` module).  When enabled, the generated build
diff --git a/Modules/CTest.cmake b/Modules/CTest.cmake
index 7759ead..8278c5c 100644
--- a/Modules/CTest.cmake
+++ b/Modules/CTest.cmake
@@ -1,68 +1,52 @@
-#.rst:
-# CTest
-# -----
-#
-# Configure a project for testing with CTest/CDash
-#
-# Include this module in the top CMakeLists.txt file of a project to
-# enable testing with CTest and dashboard submissions to CDash:
-#
-# ::
-#
-#    project(MyProject)
-#    ...
-#    include(CTest)
-#
-# The module automatically creates a BUILD_TESTING option that selects
-# whether to enable testing support (ON by default).  After including
-# the module, use code like
-#
-# ::
-#
-#    if(BUILD_TESTING)
-#      # ... CMake code to create tests ...
-#    endif()
-#
-# to creating tests when testing is enabled.
-#
-# To enable submissions to a CDash server, create a CTestConfig.cmake
-# file at the top of the project with content such as
-#
-# ::
-#
-#    set(CTEST_PROJECT_NAME "MyProject")
-#    set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
-#    set(CTEST_DROP_METHOD "http")
-#    set(CTEST_DROP_SITE "my.cdash.org")
-#    set(CTEST_DROP_LOCATION "/submit.php?project=MyProject")
-#    set(CTEST_DROP_SITE_CDASH TRUE)
-#
-# (the CDash server can provide the file to a project administrator who
-# configures 'MyProject').  Settings in the config file are shared by
-# both this CTest module and the CTest command-line tool's dashboard
-# script mode (ctest -S).
-#
-# While building a project for submission to CDash, CTest scans the
-# build output for errors and warnings and reports them with surrounding
-# context from the build log.  This generic approach works for all build
-# tools, but does not give details about the command invocation that
-# produced a given problem.  One may get more detailed reports by adding
-#
-# ::
-#
-#    set(CTEST_USE_LAUNCHERS 1)
-#
-# to the CTestConfig.cmake file.  When this option is enabled, the CTest
-# module tells CMake's Makefile generators to invoke every command in
-# the generated build system through a CTest launcher program.
-# (Currently the CTEST_USE_LAUNCHERS option is ignored on non-Makefile
-# generators.) During a manual build each launcher transparently runs
-# the command it wraps.  During a CTest-driven build for submission to
-# CDash each launcher reports detailed information when its command
-# fails or warns.  (Setting CTEST_USE_LAUNCHERS in CTestConfig.cmake is
-# convenient, but also adds the launcher overhead even for manual
-# builds.  One may instead set it in a CTest dashboard script and add it
-# to the CMake cache for the build tree.)
+#[=======================================================================[.rst:
+CTest
+-----
+
+Configure a project for testing with CTest/CDash
+
+Include this module in the top CMakeLists.txt file of a project to
+enable testing with CTest and dashboard submissions to CDash::
+
+  project(MyProject)
+  ...
+  include(CTest)
+
+The module automatically creates a ``BUILD_TESTING`` option that selects
+whether to enable testing support (``ON`` by default).  After including
+the module, use code like::
+
+  if(BUILD_TESTING)
+    # ... CMake code to create tests ...
+  endif()
+
+to creating tests when testing is enabled.
+
+To enable submissions to a CDash server, create a ``CTestConfig.cmake``
+file at the top of the project with content such as::
+
+  set(CTEST_PROJECT_NAME "MyProject")
+  set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
+  set(CTEST_DROP_METHOD "http")
+  set(CTEST_DROP_SITE "my.cdash.org")
+  set(CTEST_DROP_LOCATION "/submit.php?project=MyProject")
+  set(CTEST_DROP_SITE_CDASH TRUE)
+
+(the CDash server can provide the file to a project administrator who
+configures ``MyProject``).  Settings in the config file are shared by
+both this ``CTest`` module and the :manual:`ctest(1)` command-line
+:ref:`Dashboard Client` mode (``ctest -S``).
+
+While building a project for submission to CDash, CTest scans the
+build output for errors and warnings and reports them with surrounding
+context from the build log.  This generic approach works for all build
+tools, but does not give details about the command invocation that
+produced a given problem.  One may get more detailed reports by setting
+the :variable:`CTEST_USE_LAUNCHERS` variable::
+
+  set(CTEST_USE_LAUNCHERS 1)
+
+in the ``CTestConfig.cmake`` file.
+#]=======================================================================]
 
 #=============================================================================
 # Copyright 2005-2009 Kitware, Inc.