Updated to sphinx 7.2.6 with setup and Makefile changes (#1988)

.github/workflows/docs.yml

@@ -71,7 +71,7 @@ jobs:
       - name: docs
         shell: bash -l {0}
         run: |
-          python setup.py docs
+          make build-docs
 
       - name: publish docs
         if: github.ref == 'refs/heads/main'

Makefile

@@ -67,3 +67,8 @@ ruff:
 	ruff ${SOURCE_DIRS}
 
 check: ruff yapf mypy test
+
+build-docs:
+	sphinx-apidoc -f -M -e -T -d 3 mantidimaging **/test **/test_helpers **/eyes_tests -o docs/api/
+	sphinx-build ./docs ./docs/build/html
+	sphinx-multiversion ./docs docs/build/html/

docs/conf.py

@@ -51,6 +51,7 @@
 
 # Add custom extensions
 sys.path.append(os.path.abspath("./ext"))
+sys.path.append(os.path.abspath("../"))
 extensions.append("operations_user_doc")
 extensions.append("release_notes")
 

docs/developer_guide/documentation.rst

@@ -4,6 +4,9 @@ Documentation
 The documents are written in RST and generated with Sphinx, the build is
 performed via the Sphinx integration with setuptools.
 
+Some of the workflow uses the :code:`setup.py` file however it is the aim of 
+the developers to move away from this in the future.
+
 The documentation is version controlled along with the code, therefore it is
 beneficial to make relevant changes to the documentation as the code is
 modified.
@@ -18,7 +21,7 @@ Run the commands:
 
 .. code::
 
-   python setup.py docs
+   `make build-docs`
 
 This will create the documentation in the docs/build/html directory.
 
@@ -27,12 +30,12 @@ API Documentation
 -----------------
 
 The API documentation must be generated prior to building the documentation.
-This is done with the command: :code:`python setup.py docs_api`.
+This is done with using :code:`sphinx-apidoc`, which is done automatically in the makefile.
 
 HTML
 ----
 
-The HTML pages can be built using :code:`python setup.py docs`, which will build
+The HTML pages can be built using :code:make build-docs, which will build
 the documentation in :code:`docs/build.html`.
 
 There is a setuptools command configured to deploy the documentation to GitHub

environment-dev.yml

@@ -12,7 +12,7 @@ dependencies:
   - conda-forge::numexpr # https://github.com/mantidproject/mantidimaging/issues/1774
   - pip
   - pip:
-      - sphinx==6.2.*
+      - sphinx==7.2.*
       - git+https://github.com/samtygier-stfc/sphinx-multiversion.git@prebuild_command
       - eyes-images==5.20.*
   - yapf==0.40.*

setup.py

@@ -9,19 +9,13 @@
 import platform
 import subprocess
 from distutils.core import Command
-import sys
 from collections import defaultdict
 from pathlib import Path
 import tempfile
 import shutil
 from importlib.machinery import SourceFileLoader
 
 from setuptools import find_packages, setup
-try:
-    from sphinx.setup_command import BuildDoc
-except ModuleNotFoundError:
-    print("Warning: sphinx needed for building documentation")
-    BuildDoc = False
 
 THIS_PATH = os.path.dirname(__file__)
 
@@ -65,60 +59,6 @@ def run(self):
         g.push("--force", self.repo, "main:gh-pages")
 
 
-class GenerateSphinxApidoc(Command):
-    description = "Generate API documentation with sphinx-apidoc"
-    user_options = []
-
-    def initialize_options(self):
-        self.sphinx_options = []
-        self.module_dir = None
-        self.out_dir = None
-
-    def finalize_options(self):
-        self.sphinx_options.append("sphinx-apidoc")
-        self.sphinx_options.extend(["-f", "-M", "-e", "-T"])
-
-        self.sphinx_options.extend(["-d", "3"])
-
-        self.module_dir = "mantidimaging"
-        self.sphinx_options.append(self.module_dir)
-        self.sphinx_options.append("**/test")
-        self.sphinx_options.append("**/test_helpers")
-        self.sphinx_options.append("**/eyes_tests")
-
-        self.out_dir = "docs/api/"
-        self.sphinx_options.extend(["-o", self.out_dir])
-
-    def run(self):
-        print("Running: {}".format(" ".join(self.sphinx_options)))
-        subprocess.call(self.sphinx_options)
-
-
-class GenerateSphinxVersioned(Command):
-    description = "Generate API documentation with versions in directories"
-    user_options = []
-
-    def initialize_options(self):
-        self.sphinx_multiversion_executable = None
-        self.sphinx_multiversion_options = None
-
-    def finalize_options(self):
-        self.sphinx_multiversion_executable = "sphinx-multiversion"
-        self.sphinx_multiversion_options = ["docs", "docs/build/html"]
-
-    def run(self):
-        print("Running setup.py internal_docs_api")
-        command_docs_api = [sys.executable, "setup.py", "internal_docs_api"]
-        subprocess.check_call(command_docs_api)
-        print("Running setup.py internal_docs")
-        command_docs = [sys.executable, "setup.py", "internal_docs"]
-        subprocess.check_call(command_docs)
-        print("Running sphinx-multiversion")
-        command_sphinx_multiversion = [self.sphinx_multiversion_executable]
-        command_sphinx_multiversion.extend(self.sphinx_multiversion_options)
-        subprocess.check_call(command_sphinx_multiversion)
-
-
 class GenerateReleaseNotes(Command):
     description = "Generate release notes"
     user_options = []
@@ -270,11 +210,6 @@ def run(self):
         "Topic :: Scientific/Engineering",
     ],
     cmdclass={
-        "internal_docs_api": GenerateSphinxApidoc,
-        **({
-            "internal_docs": BuildDoc
-        } if BuildDoc else {}),
-        "docs": GenerateSphinxVersioned,
         "docs_publish": PublishDocsToGitHubPages,
         "compile_ui": CompilePyQtUiFiles,
         "create_dev_env": CreateDeveloperEnvironment,