diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8834f7b4451..e1df791417f 100644 --- a/.github/workflows/docs.yml +++ b/.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' diff --git a/Makefile b/Makefile index 5462fad8cae..8b8b4ec6b7e 100644 --- a/Makefile +++ b/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/ diff --git a/docs/conf.py b/docs/conf.py index 17cd10f5f82..1900159fc6b 100644 --- a/docs/conf.py +++ b/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") diff --git a/docs/developer_guide/documentation.rst b/docs/developer_guide/documentation.rst index fe1c39109d1..5177ea67b4b 100644 --- a/docs/developer_guide/documentation.rst +++ b/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 diff --git a/environment-dev.yml b/environment-dev.yml index 59d04819803..9b05ed1abfe 100644 --- a/environment-dev.yml +++ b/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.* diff --git a/setup.py b/setup.py index a2cedd0360c..86841b0c00a 100644 --- a/setup.py +++ b/setup.py @@ -9,7 +9,6 @@ import platform import subprocess from distutils.core import Command -import sys from collections import defaultdict from pathlib import Path import tempfile @@ -17,11 +16,6 @@ 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,