Support Sphinx 4.2+

.github/workflows/tests.yml

@@ -49,6 +49,13 @@ jobs:
         run: |
           python -m pip install --upgrade pip wheel setuptools
           python -m pip install -e .[coverage]
+          python -m pip list
+
+      - name: Test Sphinx==4.2
+        if: matrix.python-version == '3.7'
+        run: |
+          python -m pip install sphinx==4.2
+          python -m pip list
 
       - name: Build docs to store
         run: sphinx-build -b html docs/ docs/_build/html --keep-going -w warnings.txt

pyproject.toml

@@ -18,7 +18,7 @@ readme = "README.md"
 
 requires-python = ">=3.7"
 dependencies = [
-  "sphinx>=4.0.2",
+  "sphinx>=4.2",
   "beautifulsoup4",
   "docutils!=0.17.0",
   "packaging",

src/pydata_sphinx_theme/__init__.py

@@ -853,6 +853,18 @@ def _overwrite_pygments_css(app, exception=None):
 # ------------------------------------------------------------------------------
 
 
+def _traverse_or_findall(node, condition, **kwargs):
+    """Triage node.traverse (docutils <0.18.1) vs node.findall.
+    TODO: This check can be removed when the minimum supported docutils version
+    for numpydoc is docutils>=0.18.1
+    """
+    return (
+        node.findall(condition, **kwargs)
+        if hasattr(node, "findall")
+        else node.traverse(condition, **kwargs)
+    )
+
+
 class ShortenLinkTransform(SphinxPostTransform):
     """
     Shorten link when they are coming from github or gitlab and add an extra class to the tag
@@ -874,7 +886,8 @@ class ShortenLinkTransform(SphinxPostTransform):
 
     def run(self, **kwargs):
         matcher = NodeMatcher(nodes.reference)
-        for node in self.document.findall(matcher):
+        # Can just use "findall" once docutils min version >=0.18.1
+        for node in _traverse_or_findall(self.document, matcher):
             uri = node.attributes.get("refuri")
             text = next(iter(node.children), None)
             # only act if the uri and text are the same