Merge pull request #32517 from peterfpeterson/sphinx_dev_docs_fixes

Sphinx dev docs fixes

buildconfig/CMake/FindSphinx.cmake

@@ -38,3 +38,22 @@ 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
+set(SPHINX_MAIN "sphinx.__init__") # for very old sphinx
+set(SPHINX_NOCOLOR "")
+set (SPHINX_KEEPGOING "")
+if(SPHINX_VERSION VERSION_GREATER_EQUAL "1.3")
+  set(SPHINX_MAIN "sphinx")  # sphinx can be called as a module
+  # arguments new in sphinx 1.3
+  set(SPHINX_NOCOLOR "--no-color")
+endif()
+if(SPHINX_VERSION VERSION_GREATER_EQUAL "2.0")
+  # arguments new in sphinx 2.0
+  set (SPHINX_KEEPGOING "--keep-going")
+endif()

dev-docs/CMakeLists.txt

@@ -7,23 +7,15 @@ 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 -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")
-else()
-  add_custom_target(dev-docs-${BUILDER}
-                    COMMAND sphinx-build -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")
-endif()
+# hardcoded paths in them.
+# -W turns warnings into errors, but there is an issue with getting the numpy intersphinx
+add_custom_target(dev-docs-${BUILDER}
+                  COMMAND ${Python_EXECUTABLE} -m ${SPHINX_MAIN} ${SPHINX_NO_COLOR}
+                          -w dev_docs_warnings.txt
+                          ${SPHINX_KEEPGOING} -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

dev-docs/source/Testing/EngineeringDiffraction/EngineeringDiffractionTestGuide.rst

@@ -60,7 +60,7 @@ Calibration
     :width: 900px
 
 11. Check that in your save location there is a Calibration folder containing three .prm files
-   `ENGINX_305738` with the suffixes `_all_banks`, `_bank_1`, `_bank_2`.
+    `ENGINX_305738` with the suffixes `_all_banks`, `_bank_1`, `_bank_2`.
 
 12. Close down the Engineering Diffraction gui and reopen it. The Load Existing Calibration radio
     button should be checked on the Calibration tab and the path should be populated with the
@@ -207,4 +207,3 @@ This tests the serial fitting capability of the UI (where all loaded workspaces
 2. The `Serial Fit` button should now be enabled. Click it and the  group of fit workspaces should appear in the ADS, each with a row for each of the runs in the table. All the runs should have been fitted.
 
 3. The order of the runs in the serial fit should be obtainable from the log at notice level - check that this corresponds to the order of the runs in the table.
-

dev-docs/source/conf.py

@@ -11,11 +11,15 @@ from distutils.version import LooseVersion
 
 
 # -- General configuration ------------------------------------------------
-def setup(app):
-    """Called automatically by Sphinx when starting the build process
-    """
-    app.add_css_file("custom.css")
+if LooseVersion(sphinx_version) > LooseVersion("1.6"):
 
+    def setup(app):
+        """Called automatically by Sphinx when starting the build process
+        """
+        if hasattr(app, 'add_css_file'):  # >=v1.8
+            app.add_css_file("custom.css")
+        else:
+            app.add_stylesheet("custom.css")  # v1.6-1.8
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -168,7 +172,7 @@ epub_uid = "Mantid Reference: " + version
 intersphinx_mapping = {
     'h5py': ('https://h5py.readthedocs.io/en/stable/', None),
     'matplotlib': ('http://matplotlib.org', None),
-    'numpy': ('https://docs.scipy.org/doc/numpy/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
     'python': ('https://docs.python.org/3/', None),
     'SciPy': ('http://docs.scipy.org/doc/scipy/reference', None),
     'mantid': ('http://docs.mantidproject.org/', None)

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}
@@ -59,7 +49,8 @@ function (add_sphinx_build_target builder math_renderer)
     set(conf_builder ${SPHINX_CONF_DIR}/conf-${builder}.py)
   endif()
 
-  set(sphinx_options ${SPHINX_NOCOLOR} -b ${builder} -d ${DOCTREES_DIR})
+  # -W turns warnings into errors, but there is an issue with getting the numpy intersphinx
+  set(sphinx_options ${SPHINX_NOCOLOR} ${SPHINX_KEEPGOING} -b ${builder} -d ${DOCTREES_DIR})
   # add a tag to differentiate between html/qthelp in conf
   if(ARGC GREATER 3)
     set(sphinx_options ${sphinx_options} -t ${ARGV3})

docs/source/conf.py

@@ -254,7 +254,7 @@ exec(compile(open(html_theme_cfg).read(), html_theme_cfg, 'exec'))
 intersphinx_mapping = {
     'h5py': ('https://h5py.readthedocs.io/en/stable/', None),
     'matplotlib': ('https://matplotlib.org', None),
-    'numpy': ('https://docs.scipy.org/doc/numpy/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
     'python': ('https://docs.python.org/3/', None),
     'SciPy': ('https://docs.scipy.org/doc/scipy/reference', None),
     'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),

docs/source/release/v6.2.0/indirect_geometry.rst

@@ -48,7 +48,7 @@ Improvements
 
 Bugfixes
 ########
-- :ref:`IndirectILLEnertyTransfer <algm-IndirectILLEnertyTransfer>` will now perform the monitor normalisation correctly; that is, in wavelength instead of energy. It will also provide the monitor workspace as a diagnostic output, if requested.
+- :ref:`IndirectILLEnergyTransfer <algm-IndirectILLEnergyTransfer>` will now perform the monitor normalisation correctly; that is, in wavelength instead of energy. It will also provide the monitor workspace as a diagnostic output, if requested.
 
 
 :ref:`Release 6.2.0 <v6.2.0>`