Consolidate running sphinx to a single method

buildconfig/CMake/FindSphinx.cmake

@@ -38,3 +38,17 @@ include(FindPackageHandleStandardArgs)
 
 find_package_handle_standard_args(Sphinx REQUIRED_VARS SPHINX_PACKAGE_DIR SPHINX_VERSION
                                   VERSION_VAR SPHINX_VERSION)
+
+#=============================================================
+# determine arguments for running sphinx
+#=============================================================
+
+# sphinx.__main__ was introduced in version 1.3.
+# Prior to this we need to pass sphinx.__init__ to -m
+if(SPHINX_VERSION VERSION_GREATER_EQUAL "1.3")
+  set(SPHINX_MAIN "sphinx")
+  set(SPHINX_NOCOLOR "--no-color")
+else()
+  set(SPHINX_MAIN "sphinx.__init__")
+  set(SPHINX_NOCOLOR "")
+endif()

dev-docs/CMakeLists.txt

@@ -7,21 +7,14 @@ set(DOCTREE_DIR ${CMAKE_CURRENT_BINARY_DIR}/doctree)
 
 # We try to execute Sphinx directly through python -m to avoid problems with the
 # startup scripts on Windows. They are not always reliable as they can have
-# hardcoded paths in them. However, older versions of Sphinx dont't allow python
-# -m execution. Assume we are running on Linux and `sphinx-build` is available
-# in these cases
-if(EXISTS ${SPHINX_PACKAGE_DIR}/__main__.py)
-  add_custom_target(dev-docs-${BUILDER}
-                    COMMAND ${Python_EXECUTABLE} -m sphinx -b ${BUILDER} -d
-                            ${DOCTREE_DIR} ${CMAKE_CURRENT_LIST_DIR}/source
-                            ${OUT_DIR}
-                    COMMENT "Building html developer documentation")
-else()
-  add_custom_target(dev-docs-${BUILDER}
-                    COMMAND sphinx-build -b ${BUILDER} -d ${DOCTREE_DIR}
-                            ${CMAKE_CURRENT_LIST_DIR}/source ${OUT_DIR}
-                    COMMENT "Building html developer documentation")
-endif()
+# hardcoded paths in them.
+add_custom_target(dev-docs-${BUILDER}
+                  COMMAND ${Python_EXECUTABLE} -m ${SPHINX_MAIN} ${SPHINX_NO_COLOR}
+                          -w dev_docs_warnings.txt
+                          -W --keep-going -b ${BUILDER}
+                          -d ${DOCTREE_DIR} ${CMAKE_CURRENT_LIST_DIR}/source
+                          ${OUT_DIR}
+                  COMMENT "Building html developer documentation")
 
 # Group within VS and exclude from whole build
 set_target_properties(dev-docs-html

docs/CMakeLists.txt

@@ -32,16 +32,6 @@ else()
   set(ENABLE_PLOTDIRECTIVE "")
 endif()
 
-# sphinx.__main__ was introduced in version 1.3.
-# Prior to this we need to pass sphinx.__init__ to -m
-if(SPHINX_VERSION VERSION_GREATER_EQUAL "1.3")
-  set(SPHINX_MAIN "sphinx")
-  set(SPHINX_NOCOLOR "--no-color")
-else()
-  set(SPHINX_MAIN "sphinx.__init__")
-  set(SPHINX_NOCOLOR "")
-endif()
-
 # Add a sphinx build target to build documentation
 #   builder - Name of the sphinx builder: html, qthelp etc
 #   target_name - Optional target name. Default=docs-${builder}