fix compatibility with Sphinx v7.2.0

fixes #277 along with other problems found with v7.2.0 changes.

exclude sphinx7 testing with py3.8 in CI

type ignore changes for python v3.8

.github/workflows/build.yml

@@ -148,8 +148,12 @@ jobs:
           - 'sphinx4'
           - 'sphinx5'
           - 'sphinx6'
+          - 'sphinx7'
         node-version:
           - '16.x'
+        exclude:
+          - python-version: '3.8'
+            sphinx-version: 'sphinx7'
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3

noxfile.py

@@ -200,7 +200,9 @@ def docs(session: nox.Session, builder: str):
 
 @nox.session(python=SUPPORTED_PY_VER)
 @nox.parametrize(
-    "sphinx", [">=4.5,<5", ">=5,<6", ">=6,<7"], ids=["sphinx4", "sphinx5", "sphinx6"]
+    "sphinx",
+    [">=4.5,<5", ">=5,<6", ">=6,<7", ">=7,<8"],
+    ids=["sphinx4", "sphinx5", "sphinx6", "sphinx7"],
 )
 def tests(session: nox.Session, sphinx: str):
     """Run unit tests and collect code coverage analysis."""

sphinx_immaterial/__init__.py

@@ -15,6 +15,7 @@
 import sphinx.util.matching
 import sphinx.util.docutils
 import sphinx.writers.html5
+from sphinx import version_info
 
 from . import html_translator_mixin
 from .apidoc import apidoc_formatting
@@ -44,7 +45,10 @@ def _get_html_builder(base_builder: Type[sphinx.builders.html.StandaloneHTMLBuil
     """Returns a modified HTML translator."""
 
     class CustomHTMLBuilder(base_builder):  # type: ignore
-        css_files: List[sphinx.builders.html.Stylesheet]
+        if version_info < (7, 2):
+            css_files: List[sphinx.builders.html.Stylesheet]
+        else:
+            _css_files: List[sphinx.builders.html._assets._CascadingStyleSheet]  # type: ignore[name-defined]
         theme: sphinx.theming.Theme
         templates: sphinx.jinja2glue.BuiltinTemplateLoader
 
@@ -71,9 +75,14 @@ def init_js_files(self):
             if nav_adapt.READTHEDOCS is None:
                 excluded_scripts.add("_static/jquery.js")
                 excluded_scripts.add("_static/_sphinx_javascript_frameworks_compat.js")
-            self.script_files: List[sphinx.builders.html.JavaScript] = [
-                x for x in self.script_files if x.filename not in excluded_scripts
-            ]
+            if version_info < (7, 2):
+                self.script_files: List[sphinx.builders.html.JavaScript] = [
+                    x for x in self.script_files if x.filename not in excluded_scripts
+                ]
+            else:
+                self._js_files: List[sphinx.builders.html._assets._JavaScript] = [  # type: ignore[name-defined]
+                    x for x in self._js_files if x.filename not in excluded_scripts
+                ]
 
         def init_css_files(self):
             super().init_css_files()
@@ -87,11 +96,24 @@ def init_css_files(self):
                     "_static/basic.css",
                 ]
             )
-            self.css_files = [
-                x
-                for x in cast(List[sphinx.builders.html.Stylesheet], self.css_files)
-                if x.filename not in excluded
-            ]
+            if version_info < (7, 2):
+                self.css_files = [
+                    x
+                    for x in cast(
+                        List[sphinx.builders.html.Stylesheet],
+                        self._css_files,
+                    )
+                    if x.filename not in excluded
+                ]
+            else:
+                self._css_files = [
+                    x
+                    for x in cast(
+                        List[sphinx.builders.html._assets._CascadingStyleSheet],  # type: ignore[name-defined]
+                        self._css_files,
+                    )
+                    if x.filename not in excluded
+                ]
 
         def gen_additional_pages(self):
             # Prevent the search.html page from being written since this theme provides

sphinx_immaterial/apidoc/python/type_annotation_transforms.py

@@ -21,6 +21,7 @@
 import sphinx.domains.python
 import sphinx.environment
 import sphinx.util.logging
+from sphinx import version_info
 
 # `ast.unparse` added in Python 3.9
 if sys.version_info >= (3, 9):
@@ -352,9 +353,19 @@ def _monkey_patch_python_domain_to_transform_xref_titles():
     def type_to_xref(
         target: str,
         env: sphinx.environment.BuildEnvironment,
+        *args,
         suppress_prefix: bool = False,
     ) -> sphinx.addnodes.pending_xref:
-        node = orig_type_to_xref(target, env, suppress_prefix)
+        if version_info < (7, 2):
+            # suppress_prefix may not have been used like a kwarg before v7.2.0 as
+            # there was only 3 params for type_to_xref() prior to v7.2.0
+            if args:
+                suppress_prefix = args[0]
+            node = orig_type_to_xref(target, env, suppress_prefix=suppress_prefix)
+        else:
+            node = orig_type_to_xref(  # type: ignore[misc]
+                target, env, *args, suppress_prefix=suppress_prefix
+            )
         if (
             not suppress_prefix
             and len(node.children) == 1

sphinx_immaterial/postprocess_html.py

@@ -38,7 +38,7 @@ def create_sitemap(app: sphinx.application.Sphinx, exception):
     ):
         return
 
-    filename = app.outdir + "/sitemap.xml"
+    filename = str(app.outdir) + "/sitemap.xml"
     print(
         "Generating sitemap for {0} pages in "
         "{1}".format(len(sitemap_links), sphinx.util.console.colorize("blue", filename))