From eab90d130cdf7df08167eb6cd547d8d1120814d2 Mon Sep 17 00:00:00 2001
From: Brett <brettgraham@gmail.com>
Date: Thu, 27 Jul 2023 16:53:38 -0400
Subject: [PATCH 1/2] for docutils < 0.19 use traverse instead of findall

see the code comment for some details but somehow
the docs build without errors or warnings but the side
menu for sphinx-rtd-theme fails to scroll
---
 setup.cfg                  |  1 +
 sphinx_asdf/connections.py | 23 +++++++++++++++++++----
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/setup.cfg b/setup.cfg
index 117f198..da5858f 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -20,6 +20,7 @@ install_requires =
     astropy>=5.0.4
     docutils
     mistune>=3
+    packaging
     sphinx
     sphinx-astropy
     sphinx_bootstrap_theme
diff --git a/sphinx_asdf/connections.py b/sphinx_asdf/connections.py
index c9360fa..d19b497 100644
--- a/sphinx_asdf/connections.py
+++ b/sphinx_asdf/connections.py
@@ -3,8 +3,10 @@
 import posixpath
 import warnings
 
-import sphinx.builders
+import docutils
 from docutils import nodes
+import packaging.version
+import sphinx.builders
 from sphinx.util import rst
 from sphinx.util.docutils import sphinx_domains
 from sphinx.util.fileutil import copy_asset
@@ -14,6 +16,19 @@
 
 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 +41,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 +120,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 +135,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
 

From 6aa2a0ba551729588e3d4984806df12002983ecd Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Thu, 27 Jul 2023 20:59:47 +0000
Subject: [PATCH 2/2] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 sphinx_asdf/connections.py | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/sphinx_asdf/connections.py b/sphinx_asdf/connections.py
index d19b497..d5ab412 100644
--- a/sphinx_asdf/connections.py
+++ b/sphinx_asdf/connections.py
@@ -4,9 +4,9 @@
 import warnings
 
 import docutils
-from docutils import nodes
 import packaging.version
 import sphinx.builders
+from docutils import nodes
 from sphinx.util import rst
 from sphinx.util.docutils import sphinx_domains
 from sphinx.util.fileutil import copy_asset
@@ -22,10 +22,13 @@
 # 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'):
+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)