fix compatibility with Sphinx v7.2.0 (#278)

* bump mypy, pylint, and black to latest
* fix compatibility with Sphinx v7.2.0
* update unit tests for sphinx v7.2.0

.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."""

requirements/dev-black.txt

@@ -1 +1 @@
-black==23.1.0
+black==23.7.0

requirements/dev-mypy.txt

@@ -1,4 +1,4 @@
-mypy==1.0.1
+mypy==1.5.1
 types-PyYAML
 docutils-stubs
 types-jsonschema

requirements/dev-pylint.txt

@@ -1,4 +1,4 @@
-pylint==2.16.3
+pylint==2.17.5
 
 -r ./cpp.txt
 -r ./json.txt

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,21 @@ 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))

tests/conftest.py

@@ -2,7 +2,12 @@
 from typing import Dict
 
 import pytest
-from sphinx.testing.path import path as SphinxPath
+import sphinx
+
+if sphinx.version_info < (7, 2):
+    from sphinx.testing.path import path as SphinxPath
+else:
+    from pathlib import Path as SphinxPath  # type: ignore[assignment]
 
 
 pytest_plugins = ("sphinx.testing.fixtures",)

tests/python_apigen_test.py

@@ -1,10 +1,14 @@
 import pathlib
 
 import pytest
+import sphinx
 
 from sphinx_immaterial.apidoc.python.apigen import _get_api_data
 
-from sphinx.testing.path import path as SphinxPath
+if sphinx.version_info < (7, 2):
+    from sphinx.testing.path import path as SphinxPath
+else:
+    from pathlib import Path as SphinxPath  # type: ignore[assignment]
 
 pytest_plugins = ("sphinx.testing.fixtures",)
 

tests/python_transform_type_annotations_test.py

@@ -3,9 +3,13 @@
 import pytest
 
 import docutils.nodes
+import sphinx
 import sphinx.domains.python
 
-from sphinx.testing.path import path as SphinxPath
+if sphinx.version_info < (7, 2):
+    from sphinx.testing.path import path as SphinxPath
+else:
+    from pathlib import Path as SphinxPath  # type: ignore[assignment]
 
 pytest_plugins = ("sphinx.testing.fixtures",)