add compatibility with docutils~=0.18

Author: mmcky

pyproject.toml

@@ -28,7 +28,7 @@ requires-python = "~=3.7"
 dependencies = [
     "click>=7.1,<9",
     "pyyaml",
-    "sphinx>=3,<6",
+    "sphinx>=4,<6",
 ]
 
 [project.urls]

sphinx_external_toc/_compat.py

@@ -6,6 +6,8 @@
 import sys
 from typing import Any, Callable, Pattern, Type
 
+from docutils.nodes import Element
+
 if sys.version_info >= (3, 10):
     DC_SLOTS: dict = {"slots": True}
 else:
@@ -136,3 +138,10 @@ def _validator(inst, attr, value):
             member_validator(inst, attr, member)
 
     return _validator
+
+# Docutils compatibility
+
+def findall(node: Element):
+    # findall replaces traverse in docutils v0.18
+    # note a difference is that findall is an iterator
+    return getattr(node, "findall", node.traverse)

sphinx_external_toc/events.py

@@ -14,7 +14,9 @@
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.matching import Matcher, patfilter, patmatch
 
+
 from .api import Document, FileItem, GlobItem, SiteMap, UrlItem
+from ._compat import findall
 from .parsing import parse_toc_yaml
 
 logger = logging.getLogger(__name__)
@@ -164,7 +166,7 @@ def insert_toctrees(app: Sphinx, doctree: nodes.document) -> None:
     Adapted from `sphinx/directives/other.py::TocTree`
     """
     # check for existing toctrees and raise warning
-    for node in doctree.traverse(toctree_node):
+    for node in findall(doctree)(toctree_node):
         create_warning(
             app,
             doctree,
@@ -174,7 +176,7 @@ def insert_toctrees(app: Sphinx, doctree: nodes.document) -> None:
         )
 
     toc_placeholders: List[TableOfContentsNode] = list(
-        doctree.traverse(TableOfContentsNode)
+        findall(doctree)(TableOfContentsNode)
     )
 
     site_map: SiteMap = app.env.external_site_map