Merge topic 'FindCxxTest-doc' into release-3.27

676d1da38b FindCxxTest: Modernize documentation formatting
dfe0f58962 FindCxxTest: Update link to cxxtest project page

Acked-by: Kitware Robot <[email protected]>
Merge-request: !8589

Modules/FindCxxTest.cmake

@@ -7,136 +7,119 @@ FindCxxTest
 
 Find CxxTest unit testing framework.
 
-Find the CxxTest suite and declare a helper macro for creating unit
-tests and integrating them with CTest.  For more details on CxxTest
-see https://cxxtest.com
+Find the `CxxTest`_ suite and declare a helper macro for creating
+unit tests and integrating them with CTest.
 
-INPUT Variables
+.. _`CxxTest`: https://github.com/CxxTest/cxxtest#readme
 
-::
+Input Variables
+^^^^^^^^^^^^^^^
 
-   CXXTEST_USE_PYTHON [deprecated since 1.3]
-       Only used in the case both Python & Perl
-       are detected on the system to control
-       which CxxTest code generator is used.
-       Valid only for CxxTest version 3.
+``CXXTEST_USE_PYTHON``
+  .. deprecated:: 1.3
 
+  Only used in the case both Python & Perl
+  are detected on the system to control
+  which CxxTest code generator is used.
+  Valid only for CxxTest version 3.
 
+  In older versions of this Find Module,
+  this variable controlled if the Python test
+  generator was used instead of the Perl one,
+  regardless of which scripting language the
+  user had installed.
 
-::
+``CXXTEST_TESTGEN_ARGS``
+  .. versionadded:: 2.8.3
 
-       NOTE: In older versions of this Find Module,
-       this variable controlled if the Python test
-       generator was used instead of the Perl one,
-       regardless of which scripting language the
-       user had installed.
+  Specify a list of options to pass to the CxxTest code
+  generator.  If not defined, ``--error-printer`` is passed.
 
+Result Variables
+^^^^^^^^^^^^^^^^
 
+``CXXTEST_FOUND``
+  True if the CxxTest framework was found
 
-::
+``CXXTEST_INCLUDE_DIRS``
+  Where to find the CxxTest include directory
 
-   CXXTEST_TESTGEN_ARGS (since CMake 2.8.3)
-       Specify a list of options to pass to the CxxTest code
-       generator.  If not defined, --error-printer is
-       passed.
+``CXXTEST_PERL_TESTGEN_EXECUTABLE``
+  The perl-based test generator
 
+``CXXTEST_PYTHON_TESTGEN_EXECUTABLE``
+  The python-based test generator
 
+``CXXTEST_TESTGEN_EXECUTABLE``
+  .. versionadded:: 2.8.3
 
-OUTPUT Variables
+  The test generator that is actually used (chosen using user preferences
+  and interpreters found in the system)
 
-::
+``CXXTEST_TESTGEN_INTERPRETER``
+  .. versionadded:: 2.8.3
 
-   CXXTEST_FOUND
-       True if the CxxTest framework was found
-   CXXTEST_INCLUDE_DIRS
-       Where to find the CxxTest include directory
-   CXXTEST_PERL_TESTGEN_EXECUTABLE
-       The perl-based test generator
-   CXXTEST_PYTHON_TESTGEN_EXECUTABLE
-       The python-based test generator
-   CXXTEST_TESTGEN_EXECUTABLE (since CMake 2.8.3)
-       The test generator that is actually used (chosen using user preferences
-       and interpreters found in the system)
-   CXXTEST_TESTGEN_INTERPRETER (since CMake 2.8.3)
-       The full path to the Perl or Python executable on the system, on
-       platforms where the script cannot be executed using its shebang line.
+  The full path to the Perl or Python executable on the system, on
+  platforms where the script cannot be executed using its shebang line.
 
 
+Module Commands
+^^^^^^^^^^^^^^^
 
-MACROS for optional use by CMake users:
+.. command:: cxxtest_add_test
 
-::
+  Create a CxxTest runner and adds it to the CTest testing suite::
 
-    CXXTEST_ADD_TEST(<test_name> <gen_source_file> <input_files_to_testgen...>)
-       Creates a CxxTest runner and adds it to the CTest testing suite
-       Parameters:
-           test_name               The name of the test
-           gen_source_file         The generated source filename to be
-                                   generated by CxxTest
-           input_files_to_testgen  The list of header files containing the
-                                   CxxTest::TestSuite's to be included in
-                                   this runner
+    CXXTEST_ADD_TEST(<test_name> <gen_source_file>
+                     <input_files_to_testgen>...)
 
+  Parameters:
 
+  ``test_name``
+    The name of the test
 
-::
+  ``gen_source_file``
+    The generated source filename to be generated by CxxTest
 
-       #==============
-       Example Usage:
+  ``input_files_to_testgen``
+    The list of header files containing the CxxTest::TestSuite's
+    to be included in this runner
 
+Example Usage
+^^^^^^^^^^^^^
 
+The following example, if CxxTest is found, will:
 
-::
+* Invoke the testgen executable to autogenerate foo_test.cc in the
+  binary tree from "foo_test.h" in the current source directory.
+* Create an executable and test called unittest_foo.
 
-           find_package(CxxTest)
-           if(CXXTEST_FOUND)
-               include_directories(${CXXTEST_INCLUDE_DIR})
-               enable_testing()
+.. code-block:: cmake
 
+  find_package(CxxTest)
+  if(CXXTEST_FOUND)
+    include_directories(${CXXTEST_INCLUDE_DIR})
+    enable_testing()
+    CXXTEST_ADD_TEST(unittest_foo foo_test.cc
+                     ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h)
+    target_link_libraries(unittest_foo foo) # as needed
+  endif()
 
+``foo_test.h`` contains:
 
-::
-
-               CXXTEST_ADD_TEST(unittest_foo foo_test.cc
-                                 ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h)
-               target_link_libraries(unittest_foo foo) # as needed
-           endif()
-
-
-
-::
-
-              This will (if CxxTest is found):
-              1. Invoke the testgen executable to autogenerate foo_test.cc in the
-                 binary tree from "foo_test.h" in the current source directory.
-              2. Create an executable and test called unittest_foo.
-
-
-
-::
-
-      #=============
-      Example foo_test.h:
-
-
-
-::
-
-          #include <cxxtest/TestSuite.h>
-
-
+.. code-block:: c++
 
-::
+  #include <cxxtest/TestSuite.h>
+  class MyTestSuite : public CxxTest::TestSuite
+  {
+  public:
+     void testAddition( void )
+     {
+        TS_ASSERT( 1 + 1 > 1 );
+        TS_ASSERT_EQUALS( 1 + 1, 2 );
+     }
+  };
 
-          class MyTestSuite : public CxxTest::TestSuite
-          {
-          public:
-             void testAddition( void )
-             {
-                TS_ASSERT( 1 + 1 > 1 );
-                TS_ASSERT_EQUALS( 1 + 1, 2 );
-             }
-          };
 #]=======================================================================]
 
 # Version 1.4 (11/18/10) (CMake 2.8.4)