Merge pull request #75 from braingram/traverse_for_old_docutils

for docutils < 0.19 use traverse instead of findall

setup.cfg

@@ -20,6 +20,7 @@ install_requires =
     astropy>=5.0.4
     docutils
     mistune>=3
+    packaging
     sphinx
     sphinx-astropy
     sphinx_bootstrap_theme

sphinx_asdf/connections.py

@@ -3,6 +3,8 @@
 import posixpath
 import warnings
 
+import docutils
+import packaging.version
 import sphinx.builders
 from docutils import nodes
 from sphinx.util import rst
@@ -14,6 +16,22 @@
 
 TEMPLATE_PATH = os.path.join(os.path.dirname(__file__), "templates")
 
+# docutils 0.19.0 fixed a bug in traverse/findall
+# https://sourceforge.net/p/docutils/bugs/448/
+# however sphinx-rtd-theme currently pins docutils to <0.19
+# docutils has since deprecated traverse so for packages that don't
+# use sphinx-rtd-theme (and will fetch 0.19.0) using findall will
+# avoid the deprecation warnings
+if packaging.version.parse(docutils.__version__) >= packaging.version.parse("0.19.0"):
+
+    def traverse(doctree, *args, **kwargs):
+        return doctree.findall(*args, **kwargs)
+
+else:
+
+    def traverse(doctree, *args, **kwargs):
+        return doctree.traverse(*args, **kwargs)
+
 
 def find_autoasdf_directives(env, filename):
     if filename.endswith(".md"):
@@ -26,7 +44,7 @@ def find_autoasdf_directives(env, filename):
         builder.read_doc(docname)
         doctree = env.get_and_resolve_doctree(docname, builder)
 
-    return doctree.findall(schema_def)
+    return traverse(doctree, schema_def)
 
 
 def find_autoschema_references(app, genfiles):
@@ -105,7 +123,7 @@ def update_app_config(app, config):
 def handle_page_context(app, pagename, templatename, ctx, doctree):
     # Use custom template when rendering pages containing schema documentation.
     # This allows us to selectively include bootstrap
-    if doctree is not None and doctree.findall(schema_doc):
+    if doctree is not None and traverse(doctree, schema_doc):
         return os.path.join(TEMPLATE_PATH, "schema.html")
 
 
@@ -120,7 +138,7 @@ def add_labels_to_nodes(app, document):
     anonlabels = app.env.domaindata["std"]["anonlabels"]
     basepath = os.path.join("generated", app.env.config.asdf_schema_standard_prefix)
 
-    for node in document.findall():
+    for node in traverse(document):
         if isinstance(node, str) or not (isinstance(node, nodes.Node) and node["ids"]):
             continue