Merge topic 'doc-ctest-steps'

cec6248a94 Help/ctest_*: Improve documentation around the edges

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !11928

Help/command/ctest_configure.rst

@@ -30,7 +30,8 @@ The options are:
   produced by a previous call to this command.
 
 ``OPTIONS <options>``
-  Specify command-line arguments to pass to the configuration tool.
+  Specify a :ref:`semicolon-separated list <CMake Language Lists>` of
+  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
@@ -39,8 +40,9 @@ The options are:
 ``CAPTURE_CMAKE_ERROR <result-var>``
   .. versionadded:: 3.7
 
-  Store in the ``<result-var>`` variable -1 if there are any errors running
-  the command and prevent ctest from returning non-zero if an error occurs.
+  Store in the ``<result-var>`` variable ``-1`` if there are any errors running
+  the command and prevent :manual:`ctest(1)` from returning non-zero if an
+  error occurs.
 
 ``QUIET``
   .. versionadded:: 3.3

Help/command/ctest_coverage.rst

@@ -39,8 +39,9 @@ The options are:
 ``CAPTURE_CMAKE_ERROR <result-var>``
   .. versionadded:: 3.7
 
-  Store in the ``<result-var>`` variable -1 if there are any errors running
-  the command and prevent ctest from returning non-zero if an error occurs.
+  Store in the ``<result-var>`` variable ``-1`` if there are any errors running
+  the command and prevent :manual:`ctest(1)` from returning non-zero if an
+  error occurs.
 
 ``QUIET``
   .. versionadded:: 3.3

Help/command/ctest_empty_binary_directory.rst

@@ -1,7 +1,7 @@
 ctest_empty_binary_directory
 ----------------------------
 
-empties the binary directory
+Empties the binary directory.
 
 .. code-block:: cmake
 

Help/command/ctest_read_custom_files.rst

@@ -1,13 +1,13 @@
 ctest_read_custom_files
 -----------------------
 
-read CTestCustom files.
+Read CTestCustom files.
 
 .. code-block:: cmake
 
   ctest_read_custom_files(<directory>...)
 
-Read all the CTestCustom.ctest or CTestCustom.cmake files from the
+Read all the ``CTestCustom.ctest`` or ``CTestCustom.cmake`` files from the
 given directory.
 
 By default, invoking :manual:`ctest(1)` without a script will read custom

Help/command/ctest_run_script.rst

@@ -1,14 +1,21 @@
 ctest_run_script
 ----------------
 
-runs a :option:`ctest -S` script
+Run a :option:`ctest -S` script.
 
 .. code-block:: cmake
 
-  ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
-              script_file_name2 ... [RETURN_VALUE var])
+  ctest_run_script([NEW_PROCESS]
+                   <script-file>...
+                   [RETURN_VALUE <result-var>]
+                   )
 
 Runs a script or scripts much like if it was run from :option:`ctest -S`.
-If ``NEW_PROCESS`` is specified then each script will be run in a separate
-process.  If ``RETURN_VALUE`` is specified the return value of the last script
-run will be put into ``var``.
+The options are:
+
+``NEW_PROCESS``
+  Run each script in a separate process.
+
+``RETURN_VALUE <result-var>``
+  Store in the ``<result-var>`` variable ``0`` for success and
+  non-zero on failure.

Help/command/ctest_sleep.rst

@@ -1,16 +1,15 @@
 ctest_sleep
 -----------
 
-sleeps for some amount of time
-
-.. code-block:: cmake
+Sleep for some amount of time.
 
+.. signature::
   ctest_sleep(<seconds>)
 
-Sleep for given number of seconds.
-
-.. code-block:: cmake
+  Sleep for ``<seconds>`` seconds.
 
+.. signature::
   ctest_sleep(<time1> <duration> <time2>)
 
-Sleep for t=(time1 + duration - time2) seconds if t > 0.
+  Sleep for ``<time1> + <duration> - <time2>`` seconds, if this sum is greater
+  than zero.

Help/command/ctest_start.rst

@@ -1,7 +1,7 @@
 ctest_start
 -----------
 
-Starts the testing for a given model
+Perform the :ref:`CTest Start Step` as a :ref:`Dashboard Client`.
 
 .. code-block:: cmake
 

Help/command/ctest_submit.rst

@@ -83,8 +83,9 @@ The options are:
 ``CAPTURE_CMAKE_ERROR <result-var>``
   .. versionadded:: 3.13
 
-  Store in the ``<result-var>`` variable -1 if there are any errors running
-  the command and prevent ctest from returning non-zero if an error occurs.
+  Store in the ``<result-var>`` variable ``-1`` if there are any errors running
+  the command and prevent :manual:`ctest(1)` from returning non-zero if an
+  error occurs.
 
 ``QUIET``
   .. versionadded:: 3.3

Help/command/ctest_test.rst

@@ -109,8 +109,8 @@ The options are:
 
   .. versionadded:: 3.29
 
-    The ``<level>`` may be omitted, or ``0``, to let ctest use a default
-    level of parallelism, or unbounded parallelism, respectively, as
+    The ``<level>`` may be omitted, or ``0``, to let :manual:`ctest(1)` use a
+    default level of parallelism, or unbounded parallelism, respectively, as
     documented by the :option:`ctest --parallel` option.
 
 ``RESOURCE_SPEC_FILE <file>``
@@ -170,8 +170,9 @@ The options are:
 ``CAPTURE_CMAKE_ERROR <result-var>``
   .. versionadded:: 3.7
 
-  Store in the ``<result-var>`` variable -1 if there are any errors running
-  the command and prevent ctest from returning non-zero if an error occurs.
+  Store in the ``<result-var>`` variable ``-1`` if there are any errors running
+  the command and prevent :manual:`ctest(1)` from returning non-zero if an
+  error occurs.
 
 ``OUTPUT_JUNIT <file>``
   .. versionadded:: 3.21
@@ -194,9 +195,9 @@ See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE`,
 :variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` and
 :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variables, along with their
 corresponding :manual:`ctest(1)` command line options
-:option:`--test-output-size-passed <ctest --test-output-size-passed>`,
-:option:`--test-output-size-failed <ctest --test-output-size-failed>`, and
-:option:`--test-output-truncation <ctest --test-output-truncation>`.
+:ctest-option:`--test-output-size-passed`,
+:ctest-option:`--test-output-size-failed`, and
+:ctest-option:`--test-output-truncation`.
 
 .. _`Additional Test Measurements`:
 

Help/command/ctest_update.rst

@@ -26,14 +26,15 @@ The options are:
 ``CAPTURE_CMAKE_ERROR <result-var>``
   .. versionadded:: 3.13
 
-  Store in the ``<result-var>`` variable -1 if there are any errors running
-  the command and prevent ctest from returning non-zero if an error occurs.
+  Store in the ``<result-var>`` variable ``-1`` if there are any errors running
+  the command and prevent :manual:`ctest(1)` from returning non-zero if an
+  error occurs.
 
 ``QUIET``
   .. versionadded:: 3.3
 
-  Tell CTest to suppress most non-error messages that it would
-  have otherwise printed to the console.  CTest will still report
+  Suppress any CTest-specific non-error messages that would have otherwise
+  been printed to the console.  CTest will still report
   the new revision of the repository and any conflicting files
   that were found.
 

Help/command/ctest_upload.rst

@@ -13,14 +13,15 @@ The options are:
   Specify a list of files to be sent along with the build results to the
   dashboard server.
 
+``CAPTURE_CMAKE_ERROR <result-var>``
+  .. versionadded:: 3.7
+
+  Store in the ``<result-var>`` variable ``-1`` if there are any errors running
+  the command and prevent :manual:`ctest(1)` from returning non-zero if an
+  error occurs.
+
 ``QUIET``
   .. versionadded:: 3.3
 
   Suppress any CTest-specific non-error output that would have been
   printed to the console otherwise.
-
-``CAPTURE_CMAKE_ERROR <result-var>``
-  .. versionadded:: 3.7
-
-  Store in the ``<result-var>`` variable -1 if there are any errors running
-  the command and prevent ctest from returning non-zero if an error occurs.