Add individual rst files as ctest targets.

They can be disabled by turning off the SEPARATE_DOC_TESTS cmake option.
Refs #9639

Code/Mantid/Build/CMake/FindSphinx.cmake

@@ -6,6 +6,60 @@
 # set:
 #  SPHINX_FOUND
 #  SPHINX_EXECUTABLE
+#
+# It also adds the macro "sphinx_add_test" for defining
+# suites of documentation tests
+#
+#=============================================================
+# SPHINX_ADD_TEST()
+#   Adds a set of Sphinx doctests run using the sphinx_builder
+#   It is assumed that the test files are all given as relative
+#   paths ${SPHINX_SRC_DIR}
+#
+#   Parameters:
+#       _testname_prefix :: A prefix for each test that is added to ctest, the name will be
+#                           ${_testname_prefix}_TestName
+#       _doctest_runner_script :: The path to the runsphinx_doctest script
+#       ${ARGN} :: List of test files
+#=============================================================
+macro ( SPHINX_ADD_TEST _testname_prefix _doctest_runner_script )
+  # The ideal would be to simply use sphinx-build everywhere but on Windows we would need
+  # to call a debug version of sphinx-build, which we don't have. We therefore a
+  # wrapper script, to run the test.
+  # If the script finds an environment variable SPHINX_SRC_FILE then it will only process
+  # that file.
+
+  # Property for the module directory
+  if ( MSVC )
+    set ( _module_dir ${CMAKE_BINARY_DIR}/bin/Release )
+    set ( _module_dir_debug ${CMAKE_BINARY_DIR}/bin/Debug )
+    set ( _working_dir ${_module_dir} )
+    set ( _working_dir_debug ${_module_dir_debug} )
+  else()
+    set ( _module_dir ${CMAKE_BINARY_DIR}/bin )
+    set ( _working_dir ${_module_dir} )
+  endif()
+
+  foreach ( part ${ARGN} )
+      set ( _fullpath ${SPHINX_SRC_DIR}/${part} )
+      get_filename_component( _filename ${part} NAME )
+      get_filename_component( _docname ${part} NAME_WE )
+      set ( _testname "${_testname_prefix}_${_docname}" )
+
+      add_test ( NAME ${_testname}
+                 COMMAND ${PYTHON_EXECUTABLE} ${_doctest_runner_script} )
+      set_property ( TEST ${_testname} PROPERTY
+                     ENVIRONMENT "SPHINX_SRC_FILE=${_fullpath}" )
+      set_property ( TEST ${_testname} PROPERTY
+                     WORKING_DIRECTORY ${_working_dir} )
+  endforeach ()
+
+endmacro ()
+
+
+#=============================================================
+# main()
+#=============================================================
 
 find_program( SPHINX_EXECUTABLE NAME sphinx-build
   PATHS ${CMAKE_LIBRARY_PATH}/Python27/Scripts

Code/Mantid/docs/CMakeLists.txt

@@ -19,7 +19,8 @@ if ( SPHINX_FOUND )
     message (FATAL_ERROR " Install instructions at https://pypi.python.org/pypi/sphinx-bootstrap-theme/")
   endif (SPHINX_BOOTSTRAP_THEME_ERR)
 
-  # We generate a target per build type, i.e docs-html, docs-test
+  # We generate a target per build type, i.e docs-html
+  set ( SPHINX_SRC_DIR ${CMAKE_CURRENT_SOURCE_DIR}/source )
   set ( SPHINX_BUILD_DIR ${DOCS_BUILDDIR} )
   set ( SCREENSHOTS_DIR ${SPHINX_BUILD_DIR}/screenshots )
 
@@ -76,18 +77,53 @@ if ( SPHINX_FOUND )
                            EXCLUDE_FROM_ALL 1)
   endif (DOCS_HTML)
 
-  # doctest target
+  ###############################################################################
+  # Tests ( It would be nice to have this is a test sub directory but the
+  #        configure of the runsphinx file doesn't like being in two directories.
+  #        Ninja complains about multiple targets creating runsphinx.py.in)
+  #
+  # Set up two things:
+  #   - adds a global docs-test target to run all tests
+  #   - adds individual tests through ctest for each rst file.
+  ###############################################################################
+
+  ###############################################################################
+  # Overall doctest target that executes in MantidPlot
+  ###############################################################################
   set ( BUILDER doctest )
-  configure_file ( runsphinx.py.in runsphinx_doctest.py @ONLY )
+  configure_file ( ${CMAKE_CURRENT_SOURCE_DIR}/runsphinx.py.in
+                   ${CMAKE_CURRENT_BINARY_DIR}/runsphinx_doctest.py @ONLY )
+
   add_custom_target ( ${TARGET_PREFIX}-test
-    COMMAND ${PYTHON_EXECUTABLE} runsphinx_doctest.py
-    DEPENDS Framework MantidPlot
-    COMMENT "Running documentation tests"
+      COMMAND ${DOCS_RUNNER_EXE} runsphinx_doctest.py
+      DEPENDS Framework MantidPlot
+      COMMENT "Running documentation tests in MantidPlot"
   )
   # Group within VS and exclude from whole build
   set_target_properties ( ${TARGET_PREFIX}-test PROPERTIES FOLDER "Documentation"
-                                                EXCLUDE_FROM_DEFAULT_BUILD 1
-                                                EXCLUDE_FROM_ALL 1)
+                                              EXCLUDE_FROM_DEFAULT_BUILD 1
+                                              EXCLUDE_FROM_ALL 1)
+
+  ###############################################################################
+  # Add individual test targets for each file, if requested.
+  # They will require the Framework target to be built
+  ###############################################################################
+  set ( SEPARATE_DOC_TESTS TRUE BOOL
+       "If true, a separate test for each documentation file is added to ctest.")
+
+  if( SEPARATE_DOC_TESTS )
+    # The cmake documentation does not recommend using FILE (GLOB ) for populating
+    # the list of files for a target: see GLOB section here -
+    #   http://www.cmake.org/cmake/help/v2.8.8/cmake.html#command:file
+    # However, adding hundreds of files in a list here seems equally bad from a maintenance
+    # point of view as it will only get worse so we sacrifice not having to re-run cmake
+    # occasionally when a non-code file is added for readability.
+
+    file ( GLOB ALGDOC_TESTS RELATIVE ${SPHINX_SRC_DIR} ${SPHINX_SRC_DIR}/algorithms/*.rst )
+    sphinx_add_test ( AlgorithmsDocTest ${CMAKE_CURRENT_BINARY_DIR}/runsphinx_doctest.py
+                      ${ALGDOC_TESTS} )
+
+  endif()
 
   ###############################################################################
   # Installation settings

Code/Mantid/docs/runsphinx.py.in

@@ -15,13 +15,13 @@ def main():
         os.environ["SCREENSHOTS_DIR"] = screenshots_dir
 
     builder = "@BUILDER@"
-    src_dir = "@CMAKE_CURRENT_SOURCE_DIR@/source"
+    src_dir = "@SPHINX_SRC_DIR@"
     sphinx_build_dir = "@SPHINX_BUILD_DIR@"
     output_dir = os.path.join(sphinx_build_dir, builder)
     doctree_dir = os.path.join(sphinx_build_dir, "doctrees", builder)
 
     # See if we have been told to only process a particular file
-    src_file = os.environ.get("DOCS_SRC_FILE", None)
+    src_file = os.environ.get("SPHINX_SRC_FILE", None)
 
     import sphinx
     argv = [sys.executable, "-b", builder, "-d", doctree_dir, src_dir, output_dir]