Merge topic 'patch-TEST_INCLUDE_FILE-docs'

1666b715eb TEST_INCLUDE_{FILE,FILES}: Update documentation

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

Help/prop_dir/TEST_INCLUDE_FILE.rst

diff --git a/Help/prop_dir/TEST_INCLUDE_FILE.rst b/Help/prop_dir/TEST_INCLUDE_FILE.rst
index 31b2382..883b124 100644
--- a/Help/prop_dir/TEST_INCLUDE_FILE.rst
+++ b/Help/prop_dir/TEST_INCLUDE_FILE.rst
@@ -1,9 +1,14 @@
 TEST_INCLUDE_FILE
 -----------------
 
-Deprecated.  Use :prop_dir:`TEST_INCLUDE_FILES` instead.
+.. deprecated:: 3.10
 
-A cmake file that will be included when ctest is run.
+  Use the :prop_dir:`TEST_INCLUDE_FILES` directory property instead, which
+  supports specifying multiple files.
 
-If you specify ``TEST_INCLUDE_FILE``, that file will be included and
-processed when ctest is run on the directory.
+The ``TEST_INCLUDE_FILE`` directory property specifies a CMake script that is
+included and processed when ``ctest`` is run on the directory.
+
+If both the ``TEST_INCLUDE_FILE`` and :prop_dir:`TEST_INCLUDE_FILES` directory
+properties are set, the script specified in ``TEST_INCLUDE_FILE`` is included
+first, followed by the scripts listed in ``TEST_INCLUDE_FILES``.

Help/prop_dir/TEST_INCLUDE_FILES.rst

diff --git a/Help/prop_dir/TEST_INCLUDE_FILES.rst b/Help/prop_dir/TEST_INCLUDE_FILES.rst
index f9a66f4..f1c583f 100644
--- a/Help/prop_dir/TEST_INCLUDE_FILES.rst
+++ b/Help/prop_dir/TEST_INCLUDE_FILES.rst
@@ -3,7 +3,38 @@
 
 .. versionadded:: 3.10
 
-A list of cmake files that will be included when ctest is run.
+This directory property specifies a list of CMake scripts to be included and
+processed when ``ctest`` runs on the directory.  Use absolute paths, to avoid
+ambiguity.  Script files are included in the specified order.
 
-If you specify ``TEST_INCLUDE_FILES``, those files will be included and
-processed when ctest is run on the directory.
+``TEST_INCLUDE_FILES`` scripts are processed when running ``ctest``, not during
+the ``cmake`` configuration phase.  These scripts should be written as if they
+were CTest dashboard scripts.  It is common to generate such scripts dynamically
+since many variables and commands available during configuration are not
+accessible at test phase.
+
+Examples
+^^^^^^^^
+
+Setting this directory property to append one or more CMake scripts:
+
+.. code-block:: cmake
+  :caption: CMakeLists.txt
+
+  configure_file(script.cmake.in script.cmake)
+
+  set_property(
+    DIRECTORY
+    APPEND
+    PROPERTY TEST_INCLUDE_FILES
+      ${CMAKE_CURRENT_BINARY_DIR}/script.cmake
+      ${CMAKE_CURRENT_SOURCE_DIR}/foo.cmake
+      ${dir}/bar.cmake
+  )
+
+.. code-block:: cmake
+  :caption: script.cmake.in
+
+  execute_process(
+    COMMAND "@CMAKE_COMMAND@" -E echo "script.cmake executed during CTest"
+  )