Help: Revise ctest_* command documentation (#15559)

Revise documentation for the major dashboard client step ``ctest_*``
commands.  Modernize the documentation formatting.  Add some missing
options.

8 files changed, 282 insertions, 159 deletions

diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst
index 5c0a4e9..e1b7793 100644
--- a/Help/command/ctest_build.rst
+++ b/Help/command/ctest_build.rst
@@ -1,36 +1,73 @@
 ctest_build
 -----------
 
-Build the project.
+Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_build([BUILD build_dir] [TARGET target] [RETURN_VALUE res]
-              [APPEND][NUMBER_ERRORS val] [NUMBER_WARNINGS val])
+  ctest_build([BUILD <build-dir>] [APPEND]
+              [CONFIGURATION <config>]
+              [FLAGS <flags>]
+              [PROJECT_NAME <project-name>]
+              [TARGET <target-name>]
+              [NUMBER_ERRORS <num-err-var>]
+              [NUMBER_WARNINGS <num-warn-var>]
+              [RETURN_VALUE <result-var>]
+              )
 
-Builds the given build directory and stores results in Build.xml.  If no
-``BUILD`` is given, the :variable:`CTEST_BINARY_DIRECTORY` variable is used.
+Build the project and store results in ``Build.xml``
+for submission with the :command:`ctest_submit` command.
 
-The ``TARGET`` variable can be used to specify a build target.  If none is
-specified, the default target ("ALL_BUILD" for Visual Studio generators and
-"all" in others) will be built.
+The :variable:`CTEST_BUILD_COMMAND` variable may be set to explicitly
+specify the build command line.  Otherwise the build command line is
+computed automatically based on the options given.
 
-The ``RETURN_VALUE`` option specifies a variable in which to store the
-return value of the native build tool.  The ``NUMBER_ERRORS`` and
-``NUMBER_WARNINGS`` options specify variables in which to store the number
-of build errors and warnings detected.
+The options are:
 
-The ``APPEND`` option marks results for append to those previously
-submitted to a dashboard server since the last :command:`ctest_start`.  Append
-semantics are defined by the dashboard server in use.
+``BUILD <build-dir>``
+  Specify the top-level build directory.  If not given, the
+  :variable:`CTEST_BINARY_DIRECTORY` variable is used.
 
-The ``QUIET`` option suppresses any CTest-specific non-error output
-that would have been printed to the console otherwise.  The summary
-of warnings / errors, as well as the output from the native build tool
-is unaffected by this option.
+``APPEND``
+  Mark results for append to those previously submitted to a
+  dashboard server since the last :command:`ctest_start` call.
+  Append semantics are defined by the dashboard server in use.
 
-If set, the contents of the variable ``CTEST_BUILD_COMMAND`` is used to build
-the project. In addition, if set, the contents of the variable
-``CTEST_BUILD_FLAGS`` are passed as additional arguments to the underlying
-build command. This can, e.g., be used to trigger a parallel build using the
-``-j`` option of make. See :module:`ProcessorCount` for an example.
+``CONFIGURATION <config>``
+  Specify the build configuration (e.g. ``Debug``).  If not
+  specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked.
+  Otherwise the ``-C <cfg>`` option given to the :manual:`ctest(1)`
+  command will be used, if any.
+
+``FLAGS <flags>``
+  Pass additional arguments to the underlying build command.
+  If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked.
+  This can, e.g., be used to trigger a parallel build using the
+  ``-j`` option of make. See the :module:`ProcessorCount` module
+  for an example.
+
+``PROJECT_NAME <project-name>``
+  Set the name of the project to build.  This should correspond
+  to the top-level call to the :command:`project` command.
+  If not specified the ``CTEST_PROJECT_NAME`` variable will be checked.
+
+``TARGET <target-name>``
+  Specify the name of a target to build.  If not specified the
+  ``CTEST_BUILD_TARGET`` variable will be checked.  Otherwise the
+  default target will be built.  This is the "all" target
+  (called ``ALL_BUILD`` in :ref:`Visual Studio Generators`).
+
+``NUMBER_ERRORS <num-err-var>``
+  Store the number of build errors detected in the given variable.
+
+``NUMBER_WARNINGS <num-warn-var>``
+  Store the number of build warnings detected in the given variable.
+
+``RETURN_VALUE <result-var>``
+  Store the return value of the native build tool in the given variable.
+
+``QUIET``
+  Suppress any CTest-specific non-error output that would have been
+  printed to the console otherwise.  The summary of warnings / errors,
+  as well as the output from the native build tool is unaffected by
+  this option.
diff --git a/Help/command/ctest_configure.rst b/Help/command/ctest_configure.rst
index 61d9320..851c292 100644
--- a/Help/command/ctest_configure.rst
+++ b/Help/command/ctest_configure.rst
@@ -1,25 +1,39 @@
 ctest_configure
 ---------------
 
-Configure the project build tree.
+Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_configure([BUILD build_dir] [SOURCE source_dir] [APPEND]
-                  [OPTIONS options] [RETURN_VALUE res] [QUIET])
+  ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
+                  [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET])
 
-Configures the given build directory and stores results in
-Configure.xml.  If no BUILD is given, the CTEST_BINARY_DIRECTORY
-variable is used.  If no SOURCE is given, the CTEST_SOURCE_DIRECTORY
-variable is used.  The OPTIONS argument specifies command line
-arguments to pass to the configuration tool.  The RETURN_VALUE option
-specifies a variable in which to store the return value of the native
-build tool.
+Configure the project build tree and record results in ``Configure.xml``
+for submission with the :command:`ctest_submit` command.
 
-The APPEND option marks results for append to those previously
-submitted to a dashboard server since the last ctest_start.  Append
-semantics are defined by the dashboard server in use.
+The options are:
 
-The QUIET option suppresses any CTest-specific non-error messages
-that would have otherwise been printed to the console.  Output from
-the underlying configure command is not affected.
+``BUILD <build-dir>``
+  Specify the top-level build directory.  If not given, the
+  :variable:`CTEST_BINARY_DIRECTORY` variable is used.
+
+``SOURCE <source-dir>``
+  Specify the source directory.  If not given, the
+  :variable:`CTEST_SOURCE_DIRECTORY` variable is used.
+
+``APPEND``
+  Mark results for append to those previously submitted to a
+  dashboard server since the last :command:`ctest_start` call.
+  Append semantics are defined by the dashboard server in use.
+
+``OPTIONS <options>``
+  Specify command-line arguments to pass to the configuration tool.
+
+``RETURN_VALUE <result-var>``
+  Store in the ``<result-var>`` variable the return value of the native
+  configuration tool.
+
+``QUIET``
+  Suppress any CTest-specific non-error messages that would have
+  otherwise been printed to the console.  Output from the underlying
+  configure command is not affected.
diff --git a/Help/command/ctest_coverage.rst b/Help/command/ctest_coverage.rst
index bac5c1c..12429b9 100644
--- a/Help/command/ctest_coverage.rst
+++ b/Help/command/ctest_coverage.rst
@@ -1,25 +1,39 @@
 ctest_coverage
 --------------
 
-Collect coverage tool results.
+Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_coverage([BUILD build_dir] [RETURN_VALUE res] [APPEND]
-                 [LABELS label1 [label2 [...]]])
+  ctest_coverage([BUILD <build-dir>] [APPEND]
+                 [LABELS <label>...]
+                 [RETURN_VALUE <result-var>]
+                 [QUIET]
+                 )
 
-Perform the coverage of the given build directory and stores results
-in Coverage.xml.  The second argument is a variable that will hold
-value.
+Collect coverage tool results and stores them in ``Coverage.xml``
+for submission with the :command:`ctest_submit` command.
 
-The LABELS option filters the coverage report to include only source
-files labeled with at least one of the labels specified.
+The options are:
 
-The APPEND option marks results for append to those previously
-submitted to a dashboard server since the last ctest_start.  Append
-semantics are defined by the dashboard server in use.
+``BUILD <build-dir>``
+  Specify the top-level build directory.  If not given, the
+  :variable:`CTEST_BINARY_DIRECTORY` variable is used.
 
-The QUIET option suppresses any CTest-specific non-error output
-that would have been printed to the console otherwise.  The summary
-indicating how many lines of code were covered is unaffected by this
-option.
+``APPEND``
+  Mark results for append to those previously submitted to a
+  dashboard server since the last :command:`ctest_start` call.
+  Append semantics are defined by the dashboard server in use.
+
+``LABELS``
+  Filter the coverage report to include only source files labeled
+  with at least one of the labels specified.
+
+``RETURN_VALUE <result-var>``
+  Store in the ``<result-var>`` variable ``0`` if coverage tools
+  ran without error and non-zero otherwise.
+
+``QUIET``
+  Suppress any CTest-specific non-error output that would have been
+  printed to the console otherwise.  The summary indicating how many
+  lines of code were covered is unaffected by this option.
diff --git a/Help/command/ctest_memcheck.rst b/Help/command/ctest_memcheck.rst
index 56a2490..2800511 100644
--- a/Help/command/ctest_memcheck.rst
+++ b/Help/command/ctest_memcheck.rst
@@ -1,32 +1,28 @@
 ctest_memcheck
 --------------
 
-Run tests with a dynamic analysis tool.
+Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_memcheck([BUILD build_dir] [RETURN_VALUE res] [APPEND]
-             [START start number] [END end number]
-             [STRIDE stride number] [EXCLUDE exclude regex ]
-             [INCLUDE include regex]
-             [EXCLUDE_LABEL exclude regex]
-             [INCLUDE_LABEL label regex]
-             [PARALLEL_LEVEL level] )
+  ctest_memcheck([BUILD <build-dir>] [APPEND]
+                 [START <start-number>]
+                 [END <end-number>]
+                 [STRIDE <stride-number>]
+                 [EXCLUDE <exclude-regex>]
+                 [INCLUDE <include-regex>]
+                 [EXCLUDE_LABEL <label-exclude-regex>]
+                 [INCLUDE_LABEL <label-include-regex>]
+                 [PARALLEL_LEVEL <level>]
+                 [SCHEDULE_RANDOM <ON|OFF>]
+                 [STOP_TIME <time-of-day>]
+                 [RETURN_VALUE <result-var>]
+                 [QUIET]
+                 )
 
-Tests the given build directory and stores results in MemCheck.xml.
-The second argument is a variable that will hold value.  Optionally,
-you can specify the starting test number START, the ending test number
-END, the number of tests to skip between each test STRIDE, a regular
-expression for tests to run INCLUDE, or a regular expression for tests
-not to run EXCLUDE.  EXCLUDE_LABEL and INCLUDE_LABEL are regular
-expressions for tests to be included or excluded by the test property
-LABEL.  PARALLEL_LEVEL should be set to a positive number representing
-the number of tests to be run in parallel.
 
-The APPEND option marks results for append to those previously
-submitted to a dashboard server since the last ctest_start.  Append
-semantics are defined by the dashboard server in use.
+Run tests with a dynamic analysis tool and store results in
+``MemCheck.xml`` for submission with the :command:`ctest_submit`
+command.
 
-The QUIET option suppresses any CTest-specific non-error messages
-that would have otherwise been printed to the console.  Output from
-the underlying tests are not affected.
+The options are the same as those for the :command:`ctest_test` command.
diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst
index 6fa1191..6830b59 100644
--- a/Help/command/ctest_submit.rst
+++ b/Help/command/ctest_submit.rst
@@ -1,46 +1,55 @@
 ctest_submit
 ------------
 
-Submit results to a dashboard server.
+Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_submit([PARTS ...] [FILES ...]
-               [RETRY_COUNT count]
-               [RETRY_DELAY delay]
-               [RETURN_VALUE res]
+  ctest_submit([PARTS <part>...] [FILES <file>...]
+               [RETRY_COUNT <count>]
+               [RETRY_DELAY <delay>]
+               [RETURN_VALUE <result-var>]
                [QUIET]
                )
 
-By default all available parts are submitted if no PARTS or FILES are
-specified.  The PARTS option lists a subset of parts to be submitted.
-Valid part names are:
+Submit results to a dashboard server.
+By default all available parts are submitted.
 
-::
+The options are:
+
+``PARTS <part>...``
+  Specify a subset of parts to submit.  Valid part names are::
+
+    Start      = nothing
+    Update     = ctest_update results, in Update.xml
+    Configure  = ctest_configure results, in Configure.xml
+    Build      = ctest_build results, in Build.xml
+    Test       = ctest_test results, in Test.xml
+    Coverage   = ctest_coverage results, in Coverage.xml
+    MemCheck   = ctest_memcheck results, in DynamicAnalysis.xml
+    Notes      = Files listed by CTEST_NOTES_FILES, in Notes.xml
+    ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
+    Upload     = Files prepared for upload by ctest_upload(), in Upload.xml
+    Submit     = nothing
+
+``FILES <file>...``
+  Specify an explicit list of specific files to be submitted.
+  Each individual file must exist at the time of the call.
+
+``RETRY_COUNT <count>``
+  Specify how many times to retry a timed-out submission.
+
+``RETRY_DELAY <delay>``
+  Specify how long (in seconds) to wait after a timed-out submission
+  before attempting to re-submit.
+
+``RETURN_VALUE <result-var>``
+  Store in the ``<result-var>`` variable ``0`` for success and
+  non-zero on failure.
 
-  Start      = nothing
-  Update     = ctest_update results, in Update.xml
-  Configure  = ctest_configure results, in Configure.xml
-  Build      = ctest_build results, in Build.xml
-  Test       = ctest_test results, in Test.xml
-  Coverage   = ctest_coverage results, in Coverage.xml
-  MemCheck   = ctest_memcheck results, in DynamicAnalysis.xml
-  Notes      = Files listed by CTEST_NOTES_FILES, in Notes.xml
-  ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
-  Upload     = Files prepared for upload by ctest_upload(), in Upload.xml
-  Submit     = nothing
-
-The FILES option explicitly lists specific files to be submitted.
-Each individual file must exist at the time of the call.
-
-The RETRY_DELAY option specifies how long in seconds to wait after a
-timed-out submission before attempting to re-submit.
-
-The RETRY_COUNT option specifies how many times to retry a timed-out
-submission.
-
-The QUIET option suppresses all non-error messages that would have
-otherwise been printed by this call to ctest_submit().
+``QUIET``
+  Suppress all non-error messages that would have otherwise been
+  printed to the console.
 
 Submit to CDash Upload API
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst
index ee76e91..8cbb9ec 100644
--- a/Help/command/ctest_test.rst
+++ b/Help/command/ctest_test.rst
@@ -1,39 +1,79 @@
 ctest_test
 ----------
 
-Run tests in the project build tree.
+Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_test([BUILD build_dir] [APPEND]
-             [START start number] [END end number]
-             [STRIDE stride number] [EXCLUDE exclude regex ]
-             [INCLUDE include regex] [RETURN_VALUE res]
-             [EXCLUDE_LABEL exclude regex]
-             [INCLUDE_LABEL label regex]
-             [PARALLEL_LEVEL level]
-             [SCHEDULE_RANDOM on]
-             [STOP_TIME time of day])
-
-Tests the given build directory and stores results in Test.xml.  The
-second argument is a variable that will hold value.  Optionally, you
-can specify the starting test number START, the ending test number
-END, the number of tests to skip between each test STRIDE, a regular
-expression for tests to run INCLUDE, or a regular expression for tests
-to not run EXCLUDE.  EXCLUDE_LABEL and INCLUDE_LABEL are regular
-expression for test to be included or excluded by the test property
-LABEL.  PARALLEL_LEVEL should be set to a positive number representing
-the number of tests to be run in parallel.  SCHEDULE_RANDOM will
-launch tests in a random order, and is typically used to detect
-implicit test dependencies.  STOP_TIME is the time of day at which the
-tests should all stop running.
-
-The APPEND option marks results for append to those previously
-submitted to a dashboard server since the last ctest_start.  Append
-semantics are defined by the dashboard server in use.
-
-The QUIET option suppresses any CTest-specific non-error messages
-that would have otherwise been printed to the console.  Output from
-the underlying test command is not affected.  Summary info detailing
-the percentage of passing tests is also unaffected by the QUIET
-option.
+  ctest_test([BUILD <build-dir>] [APPEND]
+             [START <start-number>]
+             [END <end-number>]
+             [STRIDE <stride-number>]
+             [EXCLUDE <exclude-regex>]
+             [INCLUDE <include-regex>]
+             [EXCLUDE_LABEL <label-exclude-regex>]
+             [INCLUDE_LABEL <label-include-regex>]
+             [PARALLEL_LEVEL <level>]
+             [SCHEDULE_RANDOM <ON|OFF>]
+             [STOP_TIME <time-of-day>]
+             [RETURN_VALUE <result-var>]
+             [QUIET]
+             )
+
+Run tests in the project build tree and store results in
+``Test.xml`` for submission with the :command:`ctest_submit` command.
+
+The options are:
+
+``BUILD <build-dir>``
+  Specify the top-level build directory.  If not given, the
+  :variable:`CTEST_BINARY_DIRECTORY` variable is used.
+
+``APPEND``
+  Mark results for append to those previously submitted to a
+  dashboard server since the last :command:`ctest_start` call.
+  Append semantics are defined by the dashboard server in use.
+
+``START <start-number>``
+  Specify the beginning of a range of test numbers.
+
+``END <end-number>``
+  Specify the end of a range of test numbers.
+
+``STRIDE <stride-number>``
+  Specify the stride by which to step acorss a range of test numbers.
+
+``EXCLUDE <exclude-regex>``
+  Specify a regular expression matching test names to exclude.
+
+``INCLUDE <include-regex>``
+  Specify a regular expression matching test names to include.
+  Tests not matching this expression are excluded.
+
+``EXCLUDE_LABEL <label-exclude-regex>``
+  Specify a regular expression matching test labels to exclude.
+
+``INCLUDE_LABEL <label-include-regex>``
+  Specify a regular expression matching test labels to include.
+  Tests not matching this expression are excluded.
+
+``PARALLEL_LEVEL <level>``
+  Specify a positive number representing the number of tests to
+  be run in parallel.
+
+``SCHEDULE_RANDOM <ON|OFF>``
+  Launch tests in a random order.  This may be useful for detecting
+  implicit test dependencies.
+
+``STOP_TIME <time-of-day>``
+  Specify a time of day at which the tests should all stop running.
+
+``RETURN_VALUE <result-var>``
+  Store in the ``<result-var>`` variable ``0`` if all tests passed.
+  Store non-zero if anything went wrong.
+
+``QUIET``
+  Suppress any CTest-specific non-error messages that would have otherwise
+  been printed to the console.  Output from the underlying test command is not
+  affected.  Summary info detailing the percentage of passing tests is also
+  unaffected by the ``QUIET`` option.
diff --git a/Help/command/ctest_update.rst b/Help/command/ctest_update.rst
index 01e357b..74af1f7 100644
--- a/Help/command/ctest_update.rst
+++ b/Help/command/ctest_update.rst
@@ -1,18 +1,27 @@
 ctest_update
 ------------
 
-Update the work tree from version control.
+Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_update([SOURCE source] [RETURN_VALUE res] [QUIET])
+  ctest_update([SOURCE <source-dir>] [RETURN_VALUE <result-var>] [QUIET])
 
-Updates the given source directory and stores results in Update.xml.
-If no SOURCE is given, the CTEST_SOURCE_DIRECTORY variable is used.
-The RETURN_VALUE option specifies a variable in which to store the
-result, which is the number of files updated or -1 on error.
+Update the source tree from version control and record results in
+``Update.xml`` for submission with the :command:`ctest_submit` command.
 
-If QUIET is specified then CTest will suppress most non-error
-messages that it would have otherwise printed to the console.
-CTest will still report the new revision of the repository
-and any conflicting files that were found.
+The options are:
+
+``SOURCE <source-dir>``
+  Specify the source directory.  If not given, the
+  :variable:`CTEST_SOURCE_DIRECTORY` variable is used.
+
+``RETURN_VALUE <result-var>``
+  Store in the ``<result-var>`` variable the number of files
+  updated or ``-1`` on error.
+
+``QUIET``
+  Tell CTest to suppress most non-error messages that it would
+  have otherwise printed to the console.  CTest will still report
+  the new revision of the repository and any conflicting files
+  that were found.
diff --git a/Help/command/ctest_upload.rst b/Help/command/ctest_upload.rst
index fcd9fe4..d9630d2 100644
--- a/Help/command/ctest_upload.rst
+++ b/Help/command/ctest_upload.rst
@@ -1,14 +1,18 @@
 ctest_upload
 ------------
 
-Upload files to a dashboard server.
+Upload files to a dashboard server as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_upload(FILES ... [QUIET])
+  ctest_upload(FILES <file>... [QUIET])
 
-Pass a list of files to be sent along with the build results to the
-dashboard server.
+The options are:
 
-The QUIET option suppresses any CTest-specific non-error output
-that would have been printed to the console otherwise.
+``FILES <file>...``
+  Specify a list of files to be sent along with the build results to the
+  dashboard server.
+
+``QUIET``
+  Suppress any CTest-specific non-error output that would have been
+  printed to the console otherwise.