From cec6248a9473cc6c72946cd2e24e906f312fcb1e Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Mon, 13 Apr 2026 09:57:05 -0400 Subject: [PATCH] Help/ctest_*: Improve documentation around the edges Improve standardization and cross-references. This doesn't make any substantial changes to the existing prose. --- Help/command/ctest_configure.rst | 8 +++++--- Help/command/ctest_coverage.rst | 5 +++-- Help/command/ctest_empty_binary_directory.rst | 2 +- Help/command/ctest_read_custom_files.rst | 4 ++-- Help/command/ctest_run_script.rst | 19 +++++++++++++------ Help/command/ctest_sleep.rst | 13 ++++++------- Help/command/ctest_start.rst | 2 +- Help/command/ctest_submit.rst | 5 +++-- Help/command/ctest_test.rst | 15 ++++++++------- Help/command/ctest_update.rst | 9 +++++---- Help/command/ctest_upload.rst | 13 +++++++------ 11 files changed, 54 insertions(+), 41 deletions(-) diff --git a/Help/command/ctest_configure.rst b/Help/command/ctest_configure.rst index f23dd22244..d9b77a9817 100644 --- a/Help/command/ctest_configure.rst +++ b/Help/command/ctest_configure.rst @@ -30,7 +30,8 @@ The options are: produced by a previous call to this command. ``OPTIONS `` - Specify command-line arguments to pass to the configuration tool. + Specify a :ref:`semicolon-separated list ` of + command-line arguments to pass to the configuration tool. ``RETURN_VALUE `` Store in the ```` variable the return value of the native @@ -39,8 +40,9 @@ The options are: ``CAPTURE_CMAKE_ERROR `` .. versionadded:: 3.7 - Store in the ```` variable -1 if there are any errors running - the command and prevent ctest from returning non-zero if an error occurs. + Store in the ```` 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 diff --git a/Help/command/ctest_coverage.rst b/Help/command/ctest_coverage.rst index 319c97855c..5a850072f0 100644 --- a/Help/command/ctest_coverage.rst +++ b/Help/command/ctest_coverage.rst @@ -39,8 +39,9 @@ The options are: ``CAPTURE_CMAKE_ERROR `` .. versionadded:: 3.7 - Store in the ```` variable -1 if there are any errors running - the command and prevent ctest from returning non-zero if an error occurs. + Store in the ```` 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 diff --git a/Help/command/ctest_empty_binary_directory.rst b/Help/command/ctest_empty_binary_directory.rst index 5d26de1219..1f91d0c779 100644 --- a/Help/command/ctest_empty_binary_directory.rst +++ b/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 diff --git a/Help/command/ctest_read_custom_files.rst b/Help/command/ctest_read_custom_files.rst index 53c093e55f..48b20604b3 100644 --- a/Help/command/ctest_read_custom_files.rst +++ b/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(...) -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 diff --git a/Help/command/ctest_run_script.rst b/Help/command/ctest_run_script.rst index 0d94eb0802..734fa28e9d 100644 --- a/Help/command/ctest_run_script.rst +++ b/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] + ... + [RETURN_VALUE ] + ) 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 `` + Store in the ```` variable ``0`` for success and + non-zero on failure. diff --git a/Help/command/ctest_sleep.rst b/Help/command/ctest_sleep.rst index 42b9768f00..723c2d4e28 100644 --- a/Help/command/ctest_sleep.rst +++ b/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() -Sleep for given number of seconds. - -.. code-block:: cmake + Sleep for ```` seconds. +.. signature:: ctest_sleep( ) -Sleep for t=(time1 + duration - time2) seconds if t > 0. + Sleep for `` + - `` seconds, if this sum is greater + than zero. diff --git a/Help/command/ctest_start.rst b/Help/command/ctest_start.rst index 9c4e3dc6fd..9184fac381 100644 --- a/Help/command/ctest_start.rst +++ b/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 diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index 56a47e812b..aa238b0fda 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -83,8 +83,9 @@ The options are: ``CAPTURE_CMAKE_ERROR `` .. versionadded:: 3.13 - Store in the ```` variable -1 if there are any errors running - the command and prevent ctest from returning non-zero if an error occurs. + Store in the ```` 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 diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 8cf7134fae..ad43cd2bfd 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -109,8 +109,8 @@ The options are: .. versionadded:: 3.29 - The ```` may be omitted, or ``0``, to let ctest use a default - level of parallelism, or unbounded parallelism, respectively, as + The ```` 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 `` @@ -170,8 +170,9 @@ The options are: ``CAPTURE_CMAKE_ERROR `` .. versionadded:: 3.7 - Store in the ```` variable -1 if there are any errors running - the command and prevent ctest from returning non-zero if an error occurs. + Store in the ```` 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 `` .. 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 `, -:option:`--test-output-size-failed `, and -:option:`--test-output-truncation `. +:ctest-option:`--test-output-size-passed`, +:ctest-option:`--test-output-size-failed`, and +:ctest-option:`--test-output-truncation`. .. _`Additional Test Measurements`: diff --git a/Help/command/ctest_update.rst b/Help/command/ctest_update.rst index 836cdf1ff9..c20b8aedc4 100644 --- a/Help/command/ctest_update.rst +++ b/Help/command/ctest_update.rst @@ -26,14 +26,15 @@ The options are: ``CAPTURE_CMAKE_ERROR `` .. versionadded:: 3.13 - Store in the ```` variable -1 if there are any errors running - the command and prevent ctest from returning non-zero if an error occurs. + Store in the ```` 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. diff --git a/Help/command/ctest_upload.rst b/Help/command/ctest_upload.rst index 344979a21e..2c0f8b2bd0 100644 --- a/Help/command/ctest_upload.rst +++ b/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 `` + .. versionadded:: 3.7 + + Store in the ```` 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 `` - .. versionadded:: 3.7 - - Store in the ```` variable -1 if there are any errors running - the command and prevent ctest from returning non-zero if an error occurs.