Test on Sphinx up to 8.3

Author: domdfcoding

.github/workflows/python_ci.yml

@@ -29,15 +29,15 @@ jobs:
       matrix:
         config:
           - {python-version: "3.7", testenvs: "py37-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3},build", experimental: False}
-          - {python-version: "3.8", testenvs: "py38-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "3.9", testenvs: "py39-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "3.10", testenvs: "py310-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "3.11", testenvs: "py311-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "3.12", testenvs: "py312-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "3.13", testenvs: "py313-dev-sphinx{6.2,7.0},build", experimental: True}
-          - {python-version: "pypy-3.7", testenvs: "pypy37-sphinx{4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3},build", experimental: False}
-          - {python-version: "pypy-3.8", testenvs: "pypy38-sphinx{4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "pypy-3.9-v7.3.15", testenvs: "pypy39-sphinx{4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: True}
+          - {python-version: "3.8", testenvs: "py38-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1},build", experimental: False}
+          - {python-version: "3.9", testenvs: "py39-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1,7.2,7.3,7.4},build", experimental: False}
+          - {python-version: "3.10", testenvs: "py310-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1,7.2,7.3,7.4,8.0,8.1},build", experimental: False}
+          - {python-version: "3.11", testenvs: "py311-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1,7.2,7.3,7.4,8.0,8.1,8.2},build", experimental: False}
+          - {python-version: "3.12", testenvs: "py312-sphinx{4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1,7.2,7.3,7.4,8.0,8.1,8.2},build", experimental: False}
+          - {python-version: "3.13", testenvs: "py313-sphinx{6.2,7.0,7.1,7.2,7.3,7.4,8.0,8.1,8.2},build", experimental: False}
+          - {python-version: "pypy-3.7", testenvs: "pypy37-sphinx{4.3,4.4,4.5,5.0,5.1,5.2,5.3},build", experimental: False}
+          - {python-version: "pypy-3.8", testenvs: "pypy38-sphinx{4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1},build", experimental: False}
+          - {python-version: "pypy-3.9-v7.3.15", testenvs: "pypy39-sphinx{4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1,7.2,7.3,7.4},build", experimental: True}
 
     steps:
       - name: Checkout 🛎️

.github/workflows/python_ci_linux.yml

@@ -30,15 +30,15 @@ jobs:
       matrix:
         config:
           - {python-version: "3.7", testenvs: "py37-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3},build", experimental: False}
-          - {python-version: "3.8", testenvs: "py38-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "3.9", testenvs: "py39-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "3.10", testenvs: "py310-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "3.11", testenvs: "py311-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "3.12", testenvs: "py312-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "3.13", testenvs: "py313-dev-sphinx{6.2,7.0},build", experimental: True}
-          - {python-version: "pypy-3.7", testenvs: "pypy37-sphinx{4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3},build", experimental: False}
-          - {python-version: "pypy-3.8", testenvs: "pypy38-sphinx{4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "pypy-3.9", testenvs: "pypy39-sphinx{4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: True}
+          - {python-version: "3.8", testenvs: "py38-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1},build", experimental: False}
+          - {python-version: "3.9", testenvs: "py39-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1,7.2,7.3,7.4},build", experimental: False}
+          - {python-version: "3.10", testenvs: "py310-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1,7.2,7.3,7.4,8.0,8.1},build", experimental: False}
+          - {python-version: "3.11", testenvs: "py311-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1,7.2,7.3,7.4,8.0,8.1,8.2},build", experimental: False}
+          - {python-version: "3.12", testenvs: "py312-sphinx{4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1,7.2,7.3,7.4,8.0,8.1,8.2},build", experimental: False}
+          - {python-version: "3.13", testenvs: "py313-sphinx{6.2,7.0,7.1,7.2,7.3,7.4,8.0,8.1,8.2},build", experimental: False}
+          - {python-version: "pypy-3.7", testenvs: "pypy37-sphinx{4.3,4.4,4.5,5.0,5.1,5.2,5.3},build", experimental: False}
+          - {python-version: "pypy-3.8", testenvs: "pypy38-sphinx{4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1},build", experimental: False}
+          - {python-version: "pypy-3.9", testenvs: "pypy39-sphinx{4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1,7.2,7.3,7.4},build", experimental: True}
 
     steps:
       - name: Checkout 🛎️

.github/workflows/python_ci_macos.yml

@@ -29,15 +29,15 @@ jobs:
       matrix:
         config:
           - {python-version: "3.7", os-ver: "13", testenvs: "py37-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3},build", experimental: False}
-          - {python-version: "3.8", os-ver: "14", testenvs: "py38-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "3.9", os-ver: "14", testenvs: "py39-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "3.10", os-ver: "14", testenvs: "py310-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "3.11", os-ver: "14", testenvs: "py311-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "3.12", os-ver: "14", testenvs: "py312-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "3.13", os-ver: "14", testenvs: "py313-dev-sphinx{6.2,7.0},build", experimental: True}
-          - {python-version: "pypy-3.7", os-ver: "13", testenvs: "pypy37-sphinx{4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3},build", experimental: False}
-          - {python-version: "pypy-3.8", os-ver: "14", testenvs: "pypy38-sphinx{4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: False}
-          - {python-version: "pypy-3.9", os-ver: "14", testenvs: "pypy39-sphinx{4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0},build", experimental: True}
+          - {python-version: "3.8", os-ver: "14", testenvs: "py38-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1},build", experimental: False}
+          - {python-version: "3.9", os-ver: "14", testenvs: "py39-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1,7.2,7.3,7.4},build", experimental: False}
+          - {python-version: "3.10", os-ver: "14", testenvs: "py310-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1,7.2,7.3,7.4,8.0,8.1},build", experimental: False}
+          - {python-version: "3.11", os-ver: "14", testenvs: "py311-sphinx{3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1,7.2,7.3,7.4,8.0,8.1,8.2},build", experimental: False}
+          - {python-version: "3.12", os-ver: "14", testenvs: "py312-sphinx{4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1,7.2,7.3,7.4,8.0,8.1,8.2},build", experimental: False}
+          - {python-version: "3.13", os-ver: "14", testenvs: "py313-sphinx{6.2,7.0,7.1,7.2,7.3,7.4,8.0,8.1,8.2},build", experimental: False}
+          - {python-version: "pypy-3.7", os-ver: "13", testenvs: "pypy37-sphinx{4.3,4.4,4.5,5.0,5.1,5.2,5.3},build", experimental: False}
+          - {python-version: "pypy-3.8", os-ver: "14", testenvs: "pypy38-sphinx{4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1},build", experimental: False}
+          - {python-version: "pypy-3.9", os-ver: "14", testenvs: "pypy39-sphinx{4.3,4.4,4.5,5.0,5.1,5.2,5.3,6.0,6.1,6.2,7.0,7.1,7.2,7.3,7.4},build", experimental: True}
 
     steps:
       - name: Checkout 🛎️

pyproject.toml

@@ -33,7 +33,7 @@ base-classifiers = [
     "Topic :: Software Development :: Documentation",
     "Typing :: Typed",
 ]
-python-versions = [ "3.7", "3.8", "3.9", "3.10", "3.11", "3.12",]
+python-versions = [ "3.7", "3.8", "3.9", "3.10", "3.11", "3.12", "3.13",]
 python-implementations = [ "CPython", "PyPy",]
 platforms = [ "Windows", "macOS", "Linux",]
 license-key = "MIT"

repo_helper.yml

@@ -27,55 +27,122 @@ python_versions:
     - 6.1
     - 6.2
     - 7.0
+    - 7.1
+    - 7.2
+    - 7.3
+    - 7.4
+    - 8.0
+    - 8.1
+    - 8.2
+    - latest
  3.8:
+  matrix_exclude:
+   sphinx:
+    - 7.2
+    - 7.3
+    - 7.4
+    - 8.0
+    - 8.1
+    - 8.2
+    - latest
  3.9:
+  matrix_exclude:
+   sphinx:
+    - 8.0
+    - 8.1
+    - 8.2
  "3.10":
+  matrix_exclude:
+   sphinx:
+    - 8.2
  "3.11":
  "3.12":
- 3.13-dev:
   matrix_exclude:
    sphinx:
+    - 3.2
     - 3.3
     - 3.4
     - 3.5
     - 4.0
     - 4.1
     - 4.2
-    - 4.3
-    - 4.4
-    - 4.5
-    - 5.0
-    - 5.1
-    - 5.2
-    - 5.3
-    - 6.0
-    - 6.1
+ "3.13":
+  matrix_exclude:
+   sphinx:
+     - 3.2
+     - 3.3
+     - 3.4
+     - 3.5
+     - 4.0
+     - 4.1
+     - 4.2
+     - 4.3
+     - 4.4
+     - 4.5
+     - 5.0
+     - 5.1
+     - 5.2
+     - 5.3
+     - 6.0
+     - 6.1
  pypy37:
   matrix_exclude:
    sphinx:
+    - 3.2
     - 3.3
     - 3.4
     - 3.5
+    - 4.0
+    - 4.1
+    - 4.2
     - 6.0
     - 6.1
     - 6.2
     - 7.0
+    - 7.1
+    - 7.2
+    - 7.3
+    - 7.4
+    - 8.0
+    - 8.1
+    - 8.2
+    - latest
  pypy38:
   matrix_exclude:
    sphinx:
+    - 3.2
     - 3.3
     - 3.4
     - 3.5
+    - 4.0
+    - 4.1
+    - 4.2
+    - 7.2
+    - 7.3
+    - 7.4
+    - 8.0
+    - 8.1
+    - 8.2
+    - latest
  pypy39:
   matrix_exclude:
    sphinx:
+    - 3.2
     - 3.3
     - 3.4
     - 3.5
+    - 4.0
+    - 4.1
+    - 4.2
+    - 8.0
+    - 8.1
+    - 8.2
+    - latest
 
 exclude_files:
  - bumpversion
  - contributing
+ - tox
 
 classifiers:
  - 'Development Status :: 4 - Beta'
@@ -116,3 +183,10 @@ third_party_version_matrix:
     - 6.1
     - 6.2
     - 7.0
+    - 7.1
+    - 7.2
+    - 7.3
+    - 7.4
+    - 8.0
+    - 8.1
+    - 8.2

requirements.txt

@@ -1,3 +1,3 @@
 docutils>=0.16
-sphinx<8,>=3.2.0
+sphinx>=3.2.0
 sphinx-jinja2-compat>=0.1.0

tests/test_setup.py

@@ -1,4 +1,9 @@
+# stdlib
+from types import SimpleNamespace
+from typing import Any, Tuple
+
 # 3rd party
+import sphinx
 from sphinx.events import EventListener
 from sphinx_toolbox.testing import Sphinx, run_setup
 
@@ -27,6 +32,26 @@ def add_source_parser(self, *args, **kwargs):
 		pass
 
 
+# https://github.com/sphinx-toolbox/sphinx-toolbox/blob/d1750cf9d19f8f5e7fc5e408f0b50164ac9fad63/tests/common.py#L32
+def get_app_config_values(config: Any) -> Tuple[str, str, Any]:
+	if sphinx.version_info >= (7, 3):
+		valid_types = config.valid_types
+		default = config.default
+		rebuild = config.rebuild
+	else:
+		default, rebuild, valid_types = config
+
+	if isinstance(valid_types, (set, frozenset, tuple, list)):
+		valid_types = sorted(valid_types)
+
+	if hasattr(valid_types, "_candidates"):
+		new_valid_types = SimpleNamespace()
+		new_valid_types.candidates = sorted(valid_types._candidates)
+		valid_types = new_valid_types
+
+	return (default, rebuild, valid_types)
+
+
 def test_setup():
 
 	app: Sphinx
@@ -38,7 +63,7 @@ def test_setup():
 			"parallel_write_safe": True,
 			}
 
-	assert app.config.values["default_description_format"] == ("Default %s", "env", [str])
+	assert get_app_config_values(app.config.values["default_description_format"]) == ("Default %s", "env", [str])
 
 	assert app.events.listeners == {
 			"builder-inited": [EventListener(id=0, handler=process_default_format, priority=500)],

tests/test_sphinx_version.py

@@ -0,0 +1,13 @@
+# stdlib
+import os
+import re
+
+# 3rd party
+import sphinx
+
+
+def test_sphinx_version_against_tox():
+	m = re.match(r"py.*-sphinx(\d)\.(\d)", os.getenv("TOX_ENV_NAME", ''))
+	if m is not None:
+		target_version = tuple(map(int, m.groups()))
+		assert target_version == sphinx.version_info[:2]