Require Sphinx 8; test Sphinx 8 and 9 in CI

.github/workflows/test.yml

@@ -11,13 +11,12 @@ on:
     branches: [main]
 
 jobs:
-  test-oldsphinx:
-    runs-on: ${{ matrix.os }}-latest
+  test-sphinx:
+    runs-on: ubuntu-latest
     strategy:
       matrix:
-        os: [Ubuntu]
-        python-version: ["3.10", "3.11"]
-        sphinx-version: ["sphinx<7", "sphinx<8", "sphinx<9"]
+        python-version: ["3.12"]
+        sphinx-version: ["sphinx==8", "sphinx>=9"]
     defaults:
       run:
         shell: bash -eo pipefail {0}
@@ -66,7 +65,7 @@ jobs:
     strategy:
       matrix:
         os: ["ubuntu", "macos", "windows"]
-        python-version: ["3.12", "3.13", "3.14"]
+        python-version: ["3.13", "3.14"]
     steps:
       - uses: actions/checkout@v6
 

numpydoc/docscrape.py

@@ -632,10 +632,7 @@ def __init__(self, cls, doc=None, modulename="", func_doc=FunctionDoc, config=No
             try:
                 from sphinx.ext.autodoc._sentinels import EMPTY
             except ImportError:
-                try:
-                    from sphinx.ext.autodoc import EMPTY
-                except ImportError:
-                    EMPTY = object()
+                from sphinx.ext.autodoc import EMPTY
         else:
             ALL = object()
             EMPTY = object()

numpydoc/numpydoc.py

@@ -43,19 +43,6 @@
 HASH_LEN = 12
 
 
-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)
-    )
-
-
 def rename_references(app: SphinxApp, what, name, obj, options, lines):
     # decorate reference numbers so that there are no duplicates
     # these are later undecorated in the doctree, in relabel_references
@@ -84,7 +71,6 @@ def rename_references(app: SphinxApp, what, name, obj, options, lines):
 def _is_cite_in_numpydoc_docstring(citation_node):
     # Find DEDUPLICATION_TAG in comment as last node of sibling section
 
-    # XXX: I failed to use citation_node.traverse to do this:
     section_node = citation_node.parent
 
     def is_docstring_section(node):
@@ -96,8 +82,7 @@ def is_docstring_section(node):
             return False
 
     sibling_sections = itertools.chain(
-        _traverse_or_findall(
-            section_node,
+        section_node.findall(
             is_docstring_section,
             include_self=True,
             descend=False,
@@ -120,7 +105,7 @@ def is_docstring_section(node):
 
 def relabel_references(app: SphinxApp, doc):
     # Change 'hash-ref' to 'ref' in label text
-    for citation_node in _traverse_or_findall(doc, citation):
+    for citation_node in doc.findall(citation):
         if not _is_cite_in_numpydoc_docstring(citation_node):
             continue
         label_node = citation_node[0]
@@ -140,22 +125,22 @@ def matching_pending_xref(node):
                     and node[0].astext() == f"[{ref_text}]"
                 )
 
-            for xref_node in _traverse_or_findall(ref.parent, matching_pending_xref):
+            for xref_node in ref.parent.findall(matching_pending_xref):
                 xref_node.replace(xref_node[0], Text(f"[{new_text}]"))
             ref.replace(ref_text, new_text.copy())
 
 
 def clean_backrefs(app: SphinxApp, doc, docname):
     # only::latex directive has resulted in citation backrefs without reference
     known_ref_ids = set()
-    for ref in _traverse_or_findall(doc, reference, descend=True):
+    for ref in doc.findall(reference, descend=True):
         for id_ in ref["ids"]:
             known_ref_ids.add(id_)
     # some extensions produce backrefs to inline elements
-    for ref in _traverse_or_findall(doc, inline, descend=True):
+    for ref in doc.findall(inline, descend=True):
         for id_ in ref["ids"]:
             known_ref_ids.add(id_)
-    for citation_node in _traverse_or_findall(doc, citation, descend=True):
+    for citation_node in doc.findall(citation, descend=True):
         # remove backrefs to non-existent refs
         citation_node["backrefs"] = [
             id_ for id_ in citation_node["backrefs"] if id_ in known_ref_ids

pyproject.toml

@@ -27,7 +27,7 @@ classifiers = [
     'Topic :: Documentation',
 ]
 dependencies = [
-    'sphinx>=6',
+    'sphinx>=8',
     "tomli>=1.1.0;python_version<'3.11'",
 ]