Remove temp fix for Sphinx _static file bug

* Remove util/sphinx_static_file_temp_fix and invocation in conf.py

* Upgrade to Sphinx 8.2.3 to include fix for temp files

* Add mention of requiring Python 3.11 as comments in pyproject.toml

* Update Python versions for CI doc build (readthedocs + GitHub)

* Explain the contents of the dev deps

Author: pushfoo

.github/workflows/test.yml

@@ -83,7 +83,7 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         # python-version in must be kept in sync with .readthedocs.yaml
-        python-version: ['3.10']  # July 2024 | Match our contributor dev version; see pyproject.toml
+        python-version: ['3.11']  # July 2024 | Match our contributor dev version; see pyproject.toml
         architecture: ['x64']
 
     steps:

.readthedocs.yaml

@@ -10,7 +10,7 @@ build:
   tools:
     # If you change this, you also need to update .github/workflows/test.yml
     # to make sure doc test builds run on the same version.
-    python: "3.10"  # July 2024 | See autobuild info in pyproject.toml's dev dependencies
+    python: "3.11"  # July 2024 | See autobuild info in pyproject.toml's dev dependencies
 
 python:
   install:

doc/conf.py

@@ -122,10 +122,6 @@ def run_util(filename, run_name="__main__", init_globals=None):
     runpy.run_path(full_str, **kwargs)
 
 
-# Temp fix for Sphinx not copying static files  # pending: post-3.0 refactor
-# Enable by creating a .ENABLE_DEVMACHINE_SPHINX_STATIC_FIX
-run_util("sphinx_static_file_temp_fix.py")
-
 # Make thumbnails for the example code screenshots
 run_util("generate_example_thumbnails.py")
 # Create a tabular representation of the resources with embeds

make.py

@@ -17,9 +17,11 @@
 from contextlib import contextmanager
 from pathlib import Path
 from shutil import rmtree, which
-from typing import Union
+from typing import Union, Annotated, Optional
 from collections.abc import Generator
 
+from typer import Option
+
 PathLike = Union[Path, str, bytes]
 
 
@@ -171,23 +173,26 @@ def clean():
             os.remove(item) if os.path.isfile(item) else rmtree(item)
 
 
+JobsAnnotation = Annotated[Optional[str], Option(help="Specify a number of parallel build tasks (defaults no N_CORES)")]
+
+
 @app.command(rich_help_panel="Docs")
-def html():
+def html(jobs: JobsAnnotation = "auto"):
     """
     Build the documentation (HTML)
     """
-    run_doc([SPHINX_BUILD, "-b", "html", *ALLSPHINXOPTS, f"{BUILD_DIR}/html"])
+    run_doc([SPHINX_BUILD, "--jobs", jobs, "-b", "html", *ALLSPHINXOPTS, f"{BUILD_DIR}/html"])
     print()
     print(f"Build finished. The HTML pages are in {FULL_BUILD_DIR}/html.")
 
 
 @app.command(rich_help_panel="Docs")
-def serve():
+def serve(jobs: JobsAnnotation = "auto"):
     """
     Build and serve the docs with automatic rebuilds and live reload.
     """
     run_doc(
-        [SPHINX_AUTOBUILD, *SPHINXAUTOBUILDOPTS, "-b", "html", *ALLSPHINXOPTS, f"{BUILD_DIR}/html"]
+        [SPHINX_AUTOBUILD, *SPHINXAUTOBUILDOPTS, "--jobs", jobs, "-b", "html", *ALLSPHINXOPTS, f"{BUILD_DIR}/html"]
     )
 
 

pyproject.toml

@@ -37,15 +37,16 @@ Book = "https://learn.arcade.academy"
 [project.optional-dependencies]
 # Used for dev work
 dev = [
-    "sphinx==8.1.3",               # April 2024 | Updated 2024-07-15, 7.4+ is broken with sphinx-autobuild
-    "sphinx_rtd_theme==3.0.2",     # Nov 2024
+    # Python >= 3.11 required for development
+    "sphinx==8.2.3",               # May 2025 | Updated 2025-05-30
+    "sphinx_rtd_theme",            # Nov 2024
     "sphinx-rtd-dark-mode==1.3.0",
-    "sphinx-autobuild==2024.10.3", # April 2024 | Due to this, Python 3.10+ is required to serve docs
+    "sphinx-autobuild",            # May 2025: Seems to work with latest Sphinx now
     "sphinx-copybutton==0.5.2",    # April 2023
     "sphinx-sitemap==2.6.0",       # April 2024
     "sphinx-togglebutton==0.3.2",  # May 2025
     "pygments==2.19.1",            # 2.18 has breaking changes in lexer
-    "docutils==0.21.2",            # ?
+    "docutils==0.21.2",            # Core sphinx dependency (ReST)
     # "pyyaml==6.0.1",
     # "readthedocs-sphinx-search==0.3.2",
     # "sphinx-autodoc-typehints==2.0.1",