Tests: Document test directory layout in a README.rst

Cross-reference the CMake Source Code Guide document.
Also drop the outdated `Tests/README` file.

Help/dev/source.rst

@@ -93,7 +93,7 @@ The CMake source tree is organized as follows.
   packagers, etc.
 
 * ``Tests/``:
-  The test suite.
+  The test suite.  See `Tests/README.rst`_.
 
 * ``Utilities/``:
   Scripts, third-party source code.
@@ -103,3 +103,5 @@ The CMake source tree is organized as follows.
 
   * ``Utilities/Release/``:
     Scripts used to package CMake itself for distribution on ``cmake.org``.
+
+.. _`Tests/README.rst`: ../../Tests/README.rst

Tests/README

@@ -1,39 +0,0 @@
-If you think about adding a new testcase then here is a small checklist you
-can run through to find a proper place for it. Go through the list from the
-beginning and stop once you find something that matches your tests needs,
-i.e. if you will test a module and only need the configure mode use the
-instructions from section 2, not 3.
-
-1. Your testcase can run in CMake script mode, i.e. "cmake -P something"
-
-Put your test in Tests/CMakeTests/ directory as a .cmake.in file. It will be
-put into the test binary directory by configure_file(... @ONLY) and run from
-there. Use the AddCMakeTest() macro in Tests/CMakeTests/CMakeLists.txt to add
-your test to the test runs.
-
-2. Your test needs CMake to run in configure mode, but will not build anything
-
-This includes tests that will build something using try_compile() and friends,
-but nothing that expects add_executable(), add_library(), or add_test() to run.
-
-If the test configures the project only once and it must succeed then put it
-into the Tests/CMakeOnly/ directory.  Create a subdirectory named like your
-test and write the CMakeLists.txt you need into that subdirectory. Use the
-add_CMakeOnly_test() macro from Tests/CMakeOnly/CMakeLists.txt to add your
-test to the test runs.
-
-If the test configures the project with multiple variations and verifies
-success or failure each time then put it into the Tests/RunCMake/ directory.
-Read the instructions in Tests/RunCMake/CMakeLists.txt to add a test.
-
-3. If you are testing something from the Modules directory
-
-Put your test in the Tests/Modules/ directory. Create a subdirectory there
-named after your test. Use the ADD_TEST_MACRO macro from Tests/CMakeLists.txt
-to add your test to the test run. If you have put your stuff in
-Tests/Modules/Foo then you call it using ADD_TEST_MACRO(Module.Foo Foo).
-
-4. You are doing other stuff.
-
-Find a good place ;) In doubt mail to cmake-developers@cmake.org and ask for
-advise.

Tests/README.rst

@@ -0,0 +1,31 @@
+CMake Tests Directory
+*********************
+
+This directory contains the CMake test suite.
+See also the `CMake Source Code Guide`_.
+
+.. _`CMake Source Code Guide`: ../Help/dev/source.rst
+
+Many tests exist as immediate subdirectories, but some tests
+are organized as follows.
+
+* ``CMakeLib/``:
+  Source code, used for tests, that links to the ``CMakeLib`` library
+  defined over in ``Source/``.
+
+* ``CMakeOnly/``:
+  Deprecated.  Tests that run CMake to generate a project but not build it.
+  Superseded by ``Tests/RunCMake/``.
+
+* ``Find*/``:
+  Tests for specific find modules that can only be run on machines with
+  the corresponding packages installed.  They are enabled in
+  ``CMakeLists.txt`` by undocumented options used on CI builds.
+
+* ``Module/``:
+  Tests for specific CMake modules.
+
+* ``RunCMake/``:
+  Tests that run CMake and/or other tools while precisely checking
+  their return code and stdout/stderr content.  Useful for testing
+  error cases and diagnostic output.