From 06b416af40dda104f85597ebb84654bc930293b5 Mon Sep 17 00:00:00 2001 From: Paul V Craven Date: Mon, 20 Apr 2026 13:20:26 -0500 Subject: [PATCH 1/5] 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 --- .github/workflows/test.yml | 2 +- pyproject.toml | 27 ++++++++++++++------------- 2 files changed, 15 insertions(+), 14 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 110abf540..cf8743eb7 100644 --- a/.github/workflows/test.yml +++ b/.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: diff --git a/pyproject.toml b/pyproject.toml index 7db78ad5f..07ab95614 100644 --- a/pyproject.toml +++ b/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", + "sphinx_rtd_theme==3.1.0", + "sphinx-rtd-dark-mode==1.3.0", + "sphinx-autobuild==2024.10.3", + "sphinx-copybutton==0.5.2", + "sphinx-sitemap==2.6.0", + "sphinx-togglebutton==0.3.2", + "pygments==2.19.1", + "docutils==0.21.2", +] # 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,8 @@ dev = [ "typer==0.12.5", # Needed for make.py "wheel", "bottle", # Used for web testing playground - {include-group = "extras"} + {include-group = "extras"}, + {include-group = "docs"}, ] # Testing only From 3c5dd8b722f0b08abec86248033c6c4d2c6f77fa Mon Sep 17 00:00:00 2001 From: Paul V Craven Date: Mon, 20 Apr 2026 13:27:22 -0500 Subject: [PATCH 2/5] 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 --- .readthedocs.yaml | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 786dca377..cfa696e28 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,18 +6,16 @@ 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: - - dev + - method: uv + command: sync + groups: + - docs # Build PDF & ePub # formats: From 6a1cd9358154c90a0da5422294a985f24e704fea Mon Sep 17 00:00:00 2001 From: Paul V Craven Date: Mon, 20 Apr 2026 13:30:52 -0500 Subject: [PATCH 3/5] 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 --- .github/workflows/code_quality.yml | 4 ++-- .readthedocs.yaml | 1 + pyproject.toml | 19 +++++++++---------- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/.github/workflows/code_quality.yml b/.github/workflows/code_quality.yml index f853b24ac..47e145230 100644 --- a/.github/workflows/code_quality.yml +++ b/.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 diff --git a/.readthedocs.yaml b/.readthedocs.yaml index cfa696e28..2a850bafc 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -15,6 +15,7 @@ python: - method: uv command: sync groups: + - dev - docs # Build PDF & ePub diff --git a/pyproject.toml b/pyproject.toml index 07ab95614..8cca30114 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -40,15 +40,15 @@ extras = [ ] # Doc building (requires Python >=3.12 due to Sphinx 9.x) docs = [ - "sphinx==9.1.0", - "sphinx_rtd_theme==3.1.0", - "sphinx-rtd-dark-mode==1.3.0", - "sphinx-autobuild==2024.10.3", - "sphinx-copybutton==0.5.2", - "sphinx-sitemap==2.6.0", - "sphinx-togglebutton==0.3.2", - "pygments==2.19.1", - "docutils==0.21.2", + "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==2024.10.3; python_version >= '3.12'", + "sphinx-copybutton==0.5.2; python_version >= '3.12'", + "sphinx-sitemap==2.6.0; python_version >= '3.12'", + "sphinx-togglebutton==0.3.2; python_version >= '3.12'", + "pygments==2.19.1; python_version >= '3.12'", + "docutils==0.21.2; python_version >= '3.12'", ] # Used for dev work dev = [ @@ -66,7 +66,6 @@ dev = [ "wheel", "bottle", # Used for web testing playground {include-group = "extras"}, - {include-group = "docs"}, ] # Testing only From cd24c5e106bdac6a7579fdb6ec13064486b8f15f Mon Sep 17 00:00:00 2001 From: Paul V Craven Date: Mon, 20 Apr 2026 13:36:18 -0500 Subject: [PATCH 4/5] Bump doc dependency versions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- pyproject.toml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 8cca30114..8ad5f7ccb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -43,12 +43,12 @@ 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==2024.10.3; 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.6.0; python_version >= '3.12'", - "sphinx-togglebutton==0.3.2; python_version >= '3.12'", - "pygments==2.19.1; python_version >= '3.12'", - "docutils==0.21.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 = [ From db872c68c76409c730a397c6346e9ccd05634c1d Mon Sep 17 00:00:00 2001 From: Paul V Craven Date: Mon, 20 Apr 2026 13:45:13 -0500 Subject: [PATCH 5/5] 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 --- arcade/gl/framebuffer.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/arcade/gl/framebuffer.py b/arcade/gl/framebuffer.py index 65d109161..ae295e21d 100644 --- a/arcade/gl/framebuffer.py +++ b/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