Modules/CTest: Improve documentation formatting

Use inline reStructuredText markup and add cross-references.

1 files changed, 26 insertions, 34 deletions

diff --git a/Modules/CTest.cmake b/Modules/CTest.cmake
index 0015d4b2bb..fccef4f8fb 100644
--- a/Modules/CTest.cmake
+++ b/Modules/CTest.cmake
@@ -5,61 +5,53 @@ 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:
+enable testing with CTest and dashboard submissions to CDash::
 
-::
+  project(MyProject)
+  ...
+  include(CTest)
 
-   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::
 
-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()
+  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
+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)
+  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).
+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 adding
-
-::
+produced a given problem.  One may get more detailed reports by adding::
 
-   set(CTEST_USE_LAUNCHERS 1)
+  set(CTEST_USE_LAUNCHERS 1)
 
-to the CTestConfig.cmake file.  When this option is enabled, the CTest
+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
+(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
+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.)