feat: Add docutils_compat, fix warning (#15)

setup.cfg

@@ -10,7 +10,7 @@ default_section = THIRDPARTY
 include_trailing_comma = true
 multi_line_output = 3
 known_pytest = pytest,py
-known_first_party = gp_libs,doctest_docutils,linkify_issues,pytest_doctest_docutils
+known_first_party = gp_libs,doctest_compat,doctest_docutils,linkify_issues,pytest_doctest_docutils
 sections = FUTURE,STDLIB,PYTEST,THIRDPARTY,FIRSTPARTY,LOCALFOLDER
 line_length = 88
 

src/docutils_compat.py

@@ -0,0 +1,19 @@
+"""Helpers for cross compatibility across dependency versions."""
+import typing as t
+
+if t.TYPE_CHECKING:
+ from docutils.nodes import Node
+
+ _N = t.TypeVar("_N", bound=Node)
+
+
+def findall(node: t.Type["_N"]) -> t.Callable[..., t.Iterable["_N"]]:
+ """Iterate through nodes.
+
+ nodes.findall() replaces traverse in docutils v0.18.
+ findall is an iterator.
+
+ Based on myst_parser v0.18.1's:
+ https:/executablebooks/MyST-Parser/blob/v0.18.1/myst_parser/_compat.py
+ """
+ return getattr(node, "findall", node.traverse)

src/linkify_issues.py

@@ -5,6 +5,8 @@
 from sphinx.application import Sphinx
 from sphinx.transforms import SphinxTransform
 
+from docutils_compat import findall
+
 if sys.version_info >= (3, 8):
  from typing import TypedDict
 else:
@@ -40,7 +42,7 @@ def condition(node: nodes.Node) -> bool:
  )
  return cond
 
- for node in self.document.traverse(condition):
+ for node in findall(self.document)(condition):
  text = node.astext()
  retnodes = []
  pos = 0