diff --git a/Code/Mantid/Build/CMake/FindSphinx.cmake b/Code/Mantid/Build/CMake/FindSphinx.cmake index 99727469870f..8377095724f7 100644 --- a/Code/Mantid/Build/CMake/FindSphinx.cmake +++ b/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 diff --git a/Code/Mantid/docs/CMakeLists.txt b/Code/Mantid/docs/CMakeLists.txt index 427bcbe75168..da7f8a2ef867 100644 --- a/Code/Mantid/docs/CMakeLists.txt +++ b/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 diff --git a/Code/Mantid/docs/runsphinx.py.in b/Code/Mantid/docs/runsphinx.py.in index 8f7a6a2740c0..20e4d0a8a654 100644 --- a/Code/Mantid/docs/runsphinx.py.in +++ b/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]