Split docs deps and upgrade Sphinx to 9.1.0 (#2843)

* Split docs dependencies into separate group, upgrade Sphinx to 9.1.0

Sphinx 9.x requires Python >=3.12, but arcade supports >=3.10. Move
all doc-building deps into a 'docs' dependency group so test CI can
skip them on Python 3.10/3.11 via 'uv sync --no-group docs'.

Also upgrades sphinx-rtd-theme from 3.0.2 to 3.1.0 (required for
Sphinx 9.x compatibility).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Switch ReadTheDocs to uv with docs dependency group

RTD was using pip with extra_requirements, but deps are in
[dependency-groups] not [project.optional-dependencies], so
RTD never actually installed Sphinx. Switch to RTD's native
uv support with 'command: sync' and 'groups: [docs]'.

Also bump RTD from Python 3.10 to 3.13 and Ubuntu 24.04
(Sphinx 9.x requires Python >=3.12).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix uv resolution: add Python >=3.12 markers to docs deps

uv does universal resolution across all versions in requires-python
(>=3.10), so Sphinx 9.1.0 fails even on Python 3.13. Fix by:

- Adding 'python_version >= 3.12' markers to all docs group deps
- Removing docs include from dev group (keep them independent)
- Code quality CI uses 'uv sync --group docs' explicitly
- RTD installs both dev and docs groups

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Bump doc dependency versions

- pygments 2.19.1 → 2.20.0
- sphinx-togglebutton 0.3.2 → 0.4.5
- sphinx-sitemap 2.6.0 → 2.9.0
- sphinx-autobuild 2024.10.3 → 2025.8.25
- docutils 0.21.2 → 0.22.4

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix Sphinx warnings for ambiguous x/y cross-references

The ':type: tuple (x, y, width, height)' syntax caused Sphinx to
interpret x and y as cross-references to class attributes. Use
inline code markup instead.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Paul V Craven <paul.craven@optimizley.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

.github/workflows/code_quality.yml

@@ -29,7 +29,7 @@ jobs:
           enable-cache: true
 
       - name: Sync UV project
-        run: uv sync
+        run: uv sync --group docs
 
       - name: Formatting (Ruff)
         if: success()
@@ -75,7 +75,7 @@ jobs:
           enable-cache: true
 
       - name: Sync UV Project
-        run: uv sync
+        run: uv sync --group docs
 
       - name: build-docs
         run: uv run make.py docs-full

.github/workflows/test.yml

@@ -38,7 +38,7 @@ jobs:
           enable-cache: true
 
       - name: Sync UV project
-        run: uv sync
+        run: uv sync --no-group docs
 
       - name: Run tests
         env:

.readthedocs.yaml

@@ -6,18 +6,17 @@ sphinx:
   configuration: doc/conf.py
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   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.13"
 
 python:
   install:
-    - method: pip
-      path: .
-      extra_requirements:
+    - method: uv
+      command: sync
+      groups:
         - dev
+        - docs
 
 # Build PDF & ePub
 # formats:

arcade/gl/framebuffer.py

@@ -128,7 +128,7 @@ def scissor(self) -> tuple[int, int, int, int] | None:
             # Disable scissoring
             ctx.scissor = None
 
-        :type: tuple (x, y, width, height)
+        The value is a tuple of ``(x, y, width, height)`` or ``None`` to disable.
 
         """
         return self._scissor

pyproject.toml

@@ -38,20 +38,20 @@ Book = "https://learn.arcade.academy"
 extras = [
     "pymunk~=7.2.0"
 ]
+# Doc building (requires Python >=3.12 due to Sphinx 9.x)
+docs = [
+    "sphinx==9.1.0; python_version >= '3.12'",
+    "sphinx_rtd_theme==3.1.0; python_version >= '3.12'",
+    "sphinx-rtd-dark-mode==1.3.0; python_version >= '3.12'",
+    "sphinx-autobuild==2025.8.25; python_version >= '3.12'",
+    "sphinx-copybutton==0.5.2; python_version >= '3.12'",
+    "sphinx-sitemap==2.9.0; python_version >= '3.12'",
+    "sphinx-togglebutton==0.4.5; python_version >= '3.12'",
+    "pygments==2.20.0; python_version >= '3.12'",
+    "docutils==0.22.4; python_version >= '3.12'",
+]
 # 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
-    "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-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",            # ?
-    # "pyyaml==6.0.1",
-    # "readthedocs-sphinx-search==0.3.2",
-    # "sphinx-autodoc-typehints==2.0.1",
     # --- tools and build
     "pytest",
     "pytest-cov",
@@ -65,7 +65,7 @@ dev = [
     "typer==0.12.5",    # Needed for make.py
     "wheel",
     "bottle",            # Used for web testing playground
-    {include-group = "extras"}
+    {include-group = "extras"},
 ]
 
 # Testing only