Tests/RunCMake: Move documentation to a README.rst

2 files changed, 52 insertions, 36 deletions

diff --git a/Tests/RunCMake/CMakeLists.txt b/Tests/RunCMake/CMakeLists.txt
index 1c23bcd..fc730a7 100644
--- a/Tests/RunCMake/CMakeLists.txt
+++ b/Tests/RunCMake/CMakeLists.txt
@@ -1,39 +1,4 @@
-# This directory contains tests that run CMake to configure a project
-# but do not actually build anything.  To add a test:
-#
-# 1.) Add a subdirectory named for the test.
-#
-# 2.) Call add_RunCMake_test and pass the test directory name.
-#
-# 3.) Create a RunCMakeTest.cmake script in the directory containing
-#   include(RunCMake)
-#   run_cmake(SubTest1)
-#   ...
-#   run_cmake(SubTestN)
-# where SubTest1..SubTestN are sub-test names each corresponding to
-# an independent CMake run and project configuration.
-#
-# 3.) Create a CMakeLists.txt file in the directory containing
-#   cmake_minimum_required(...)
-#   project(${RunCMake_TEST} NONE) # or languages needed
-#   include(${RunCMake_TEST}.cmake)
-# where "${RunCMake_TEST}" is literal.  A value for RunCMake_TEST
-# will be passed to CMake by the run_cmake macro when running each
-# sub-test.
-#
-# 4.) Create a <SubTest>.cmake file for each sub-test named above
-# containing the actual test code.  Optionally create files
-# containing expected test results:
-#   <SubTest>-result.txt  = Process result expected if not "0"
-#   <SubTest>-stdout.txt  = Regex matching expected stdout content
-#   <SubTest>-stderr.txt  = Regex matching expected stderr content
-#   <SubTest>-check.cmake = Custom result check
-# Note that trailing newlines will be stripped from actual and expected test
-# output before matching against the stdout and stderr expressions.
-# The code in <SubTest>-check.cmake may use variables
-#   RunCMake_TEST_SOURCE_DIR = Top of test source tree
-#   RunCMake_TEST_BINARY_DIR = Top of test binary tree
-# and an failure must store a message in RunCMake_TEST_FAILED.
+# See adjacent README.rst for documentation of this test infrastructure.
 
 macro(add_RunCMake_test test)
   add_test(RunCMake.${test} ${CMAKE_CMAKE_COMMAND}
diff --git a/Tests/RunCMake/README.rst b/Tests/RunCMake/README.rst
new file mode 100644
index 0000000..d4159a5
--- /dev/null
+++ b/Tests/RunCMake/README.rst
@@ -0,0 +1,51 @@
+This directory contains tests that run CMake to configure a project
+but do not actually build anything.  To add a test:
+
+1. Add a subdirectory named for the test, say ``<Test>/``.
+
+2. In ``./CMakeLists.txt`` call ``add_RunCMake_test`` and pass the
+   test directory name ``<Test>``.
+
+3. Create script ``<Test>/RunCMakeTest.cmake`` in the directory containing::
+
+    include(RunCMake)
+    run_cmake(SubTest1)
+    ...
+    run_cmake(SubTestN)
+
+   where ``SubTest1`` through ``SubTestN`` are sub-test names each
+   corresponding to an independent CMake run and project configuration.
+
+4. Create file ``<Test>/CMakeLists.txt`` in the directory containing::
+
+    cmake_minimum_required(...)
+    project(${RunCMake_TEST} NONE) # or languages needed
+    include(${RunCMake_TEST}.cmake)
+
+   where ``${RunCMake_TEST}`` is literal.  A value for ``RunCMake_TEST``
+   will be passed to CMake by the ``run_cmake`` macro when running each
+   sub-test.
+
+5. Create a ``<Test>/<SubTest>.cmake`` file for each sub-test named
+   above containing the actual test code.  Optionally create files
+   containing expected test results:
+
+   ``<SubTest>-result.txt``
+    Process result expected if not "0"
+   ``<SubTest>-stdout.txt``
+    Regex matching expected stdout content
+   ``<SubTest>-stderr.txt``
+    Regex matching expected stderr content
+   ``<SubTest>-check.cmake``
+    Custom result check.
+
+   Note that trailing newlines will be stripped from actual and expected
+   test output before matching against the stdout and stderr expressions.
+   The code in ``<SubTest>-check.cmake`` may use variables
+
+   ``RunCMake_TEST_SOURCE_DIR``
+    Top of test source tree
+   ``RunCMake_TEST_BINARY_DIR``
+    Top of test binary tree
+
+   and an failure must store a message in ``RunCMake_TEST_FAILED``.