⬆️ Add Sphinx 9 support (#255)

This PR adds support for Sphinx 9.x while maintaining backward
compatibility with Sphinx 7.x and 8.x. The changes address a breaking
change in docutils 0.22+ regarding boolean attribute serialization in
XML output.

**Changes:**
- Updated dependency version constraints to support Sphinx 9 and
myst-parser 4-5
- Added Sphinx 9.0 to the CI test matrix for Ubuntu and Windows
environments
- Introduced XML normalization fixture to handle docutils 0.22+ boolean
serialization changes

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: chrisjsewell

.github/workflows/ci.yml

@@ -28,17 +28,21 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         python-version: ["3.11", "3.12", "3.13", "3.14"]
-        sphinx-version: ["~=7.0", "~=8.0"]
+        sphinx-version: ["~=7.0", "~=8.0", "~=9.0"]
         extras: ["testing"]
         include:
         - os: windows-latest
           python-version: "3.11"
           sphinx-version: "~=7.0"
           extras: "testing"
         - os: windows-latest
-          python-version: "3.14"
+          python-version: "3.13"
           sphinx-version: "~=8.0"
           extras: "testing"
+        - os: windows-latest
+          python-version: "3.14"
+          sphinx-version: "~=9.0"
+          extras: "testing"
 
     runs-on: ${{ matrix.os }}
 

pyproject.toml

@@ -27,17 +27,17 @@ classifiers = [
 ]
 keywords = ["sphinx", "extension", "material design", "web components"]
 requires-python = ">=3.11"
-dependencies = ["sphinx>=7,<9"]
+dependencies = ["sphinx>=7,<10"]
 
 [project.urls]
 Homepage = "https://github.com/executablebooks/sphinx-design"
 Documentation = "https://sphinx-design.readthedocs.io"
 
 [project.optional-dependencies]
 code-style = ["pre-commit>=3,<4"]
-rtd = ["myst-parser>=3,<5"]
+rtd = ["myst-parser>=4,<6"]
 testing = [
-    "myst-parser>=3,<5",
+    "myst-parser>=4,<6",
     "pytest~=8.3",
     "pytest-cov",
     "pytest-regressions",

tests/conftest.py

@@ -1,7 +1,9 @@
 import os
 from pathlib import Path
+import re
 from typing import Any
 
+from docutils import __version_info__ as docutils_version_info
 from docutils import nodes
 import pytest
 from sphinx import version_info
@@ -88,3 +90,39 @@ def _create_project(
         return SphinxBuilder(app, src_path)
 
     yield _create_project
+
+
+DOCUTILS_0_22_PLUS = docutils_version_info >= (0, 22)
+
+
+@pytest.fixture
+def normalize_doctree_xml():
+    """Normalize docutils XML output for cross-version compatibility.
+
+    In docutils 0.22+, boolean attributes are serialized as "1"/"0"
+    instead of "True"/"False". This function normalizes to the old format
+    for consistent test fixtures.
+    """
+
+    def _normalize(text: str) -> str:
+        if DOCUTILS_0_22_PLUS:
+            # Normalize new format (1/0) to old format (1/0)
+            # Only replace when it's clearly a boolean attribute value
+            # Pattern: attribute="1" or attribute="0"
+            attrs = [
+                "checked",
+                "force",
+                "has_title",
+                "internal",
+                "is_div",
+                "linenos",
+                "opened",
+                "refexplicit",
+                "refwarn",
+                "selected",
+            ]
+            text = re.sub(rf' ({"|".join(attrs)})="1"', r' \1="True"', text)
+            text = re.sub(rf' ({"|".join(attrs)})="0"', r' \1="False"', text)
+        return text
+
+    return _normalize

tests/test_snippets.py

@@ -33,7 +33,10 @@ def write_assets(src_path: Path):
     ids=[path.name[: -len(path.suffix)] for path in SNIPPETS_GLOB_RST],
 )
 def test_snippets_rst(
-    sphinx_builder: Callable[..., SphinxBuilder], path: Path, file_regression
+    sphinx_builder: Callable[..., SphinxBuilder],
+    path: Path,
+    file_regression,
+    normalize_doctree_xml,
 ):
     """Test snippets written in RestructuredText (before post-transforms)."""
     builder = sphinx_builder(conf_kwargs={"extensions": ["sphinx_design"]})
@@ -44,7 +47,7 @@ def test_snippets_rst(
     doctree = builder.get_doctree("index", post_transforms=False)
     doctree.attributes.pop("translation_progress", None)  # added in sphinx 7.1
     file_regression.check(
-        doctree.pformat(),
+        normalize_doctree_xml(doctree.pformat()),
         basename=f"snippet_pre_{path.name[: -len(path.suffix)]}",
         extension=".xml",
         encoding="utf8",
@@ -58,7 +61,10 @@ def test_snippets_rst(
 )
 @pytest.mark.skipif(not MYST_INSTALLED, reason="myst-parser not installed")
 def test_snippets_myst(
-    sphinx_builder: Callable[..., SphinxBuilder], path: Path, file_regression
+    sphinx_builder: Callable[..., SphinxBuilder],
+    path: Path,
+    file_regression,
+    normalize_doctree_xml,
 ):
     """Test snippets written in MyST Markdown (before post-transforms)."""
     builder = sphinx_builder()
@@ -69,7 +75,7 @@ def test_snippets_myst(
     doctree = builder.get_doctree("index", post_transforms=False)
     doctree.attributes.pop("translation_progress", None)  # added in sphinx 7.1
     file_regression.check(
-        doctree.pformat(),
+        normalize_doctree_xml(doctree.pformat()),
         basename=f"snippet_pre_{path.name[: -len(path.suffix)]}",
         extension=".xml",
         encoding="utf8",
@@ -82,7 +88,10 @@ def test_snippets_myst(
     ids=[path.name[: -len(path.suffix)] for path in SNIPPETS_GLOB_RST],
 )
 def test_snippets_rst_post(
-    sphinx_builder: Callable[..., SphinxBuilder], path: Path, file_regression
+    sphinx_builder: Callable[..., SphinxBuilder],
+    path: Path,
+    file_regression,
+    normalize_doctree_xml,
 ):
     """Test snippets written in RestructuredText (after HTML post-transforms)."""
     builder = sphinx_builder(conf_kwargs={"extensions": ["sphinx_design"]})
@@ -93,7 +102,7 @@ def test_snippets_rst_post(
     doctree = builder.get_doctree("index", post_transforms=True)
     doctree.attributes.pop("translation_progress", None)  # added in sphinx 7.1
     file_regression.check(
-        doctree.pformat(),
+        normalize_doctree_xml(doctree.pformat()),
         basename=f"snippet_post_{path.name[: -len(path.suffix)]}",
         extension=".xml",
         encoding="utf8",
@@ -107,7 +116,10 @@ def test_snippets_rst_post(
 )
 @pytest.mark.skipif(not MYST_INSTALLED, reason="myst-parser not installed")
 def test_snippets_myst_post(
-    sphinx_builder: Callable[..., SphinxBuilder], path: Path, file_regression
+    sphinx_builder: Callable[..., SphinxBuilder],
+    path: Path,
+    file_regression,
+    normalize_doctree_xml,
 ):
     """Test snippets written in MyST Markdown (after HTML post-transforms)."""
     builder = sphinx_builder()
@@ -118,7 +130,7 @@ def test_snippets_myst_post(
     doctree = builder.get_doctree("index", post_transforms=True)
     doctree.attributes.pop("translation_progress", None)  # added in sphinx 7.1
     file_regression.check(
-        doctree.pformat(),
+        normalize_doctree_xml(doctree.pformat()),
         basename=f"snippet_post_{path.name[: -len(path.suffix)]}",
         extension=".xml",
         encoding="utf8",
@@ -164,7 +176,7 @@ def test_sd_hide_title_myst(
 
 @pytest.mark.skipif(not MYST_INSTALLED, reason="myst-parser not installed")
 def test_sd_custom_directives(
-    sphinx_builder: Callable[..., SphinxBuilder], file_regression
+    sphinx_builder: Callable[..., SphinxBuilder], file_regression, normalize_doctree_xml
 ):
     """Test that the defaults are used."""
     builder = sphinx_builder(
@@ -188,7 +200,7 @@ def test_sd_custom_directives(
     doctree = builder.get_doctree("index", post_transforms=False)
     doctree.attributes.pop("translation_progress", None)  # added in sphinx 7.1
     file_regression.check(
-        doctree.pformat(),
+        normalize_doctree_xml(doctree.pformat()),
         basename="sd_custom_directives",
         extension=".xml",
         encoding="utf8",