♻️ REFACTOR: Change insert_toctrees to a transform

So we can apply it earlier.

Author: chrisjsewell

sphinx_external_toc/__init__.py

@@ -13,7 +13,7 @@ def setup(app: "Sphinx") -> dict:
     """Initialize the Sphinx extension."""
     from .events import (
         add_changed_toctrees,
-        insert_toctrees,
+        InsertToctrees,
         parse_toc_to_env,
         TableofContents,
     )
@@ -28,7 +28,6 @@ def setup(app: "Sphinx") -> dict:
     app.connect("config-inited", parse_toc_to_env, priority=900)
     app.connect("env-get-outdated", add_changed_toctrees)
     app.add_directive("tableofcontents", TableofContents)
-    # Note: this needs to occur before `TocTreeCollector.process_doc` (default priority 500)
-    app.connect("doctree-read", insert_toctrees, priority=100)
+    app.add_transform(InsertToctrees)
 
     return {"version": __version__, "parallel_read_safe": True}

sphinx_external_toc/events.py

@@ -9,6 +9,7 @@
 from sphinx.config import Config
 from sphinx.environment import BuildEnvironment
 from sphinx.errors import ExtensionError
+from sphinx.transforms import SphinxTransform
 from sphinx.util import docname_join, logging
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.matching import Matcher, patfilter, patmatch
@@ -262,3 +263,16 @@ def insert_toctrees(app: Sphinx, doctree: nodes.document) -> None:
         # since `TocTreeCollector.process_doc` expects it in a section
         # TODO check if there is this is always ok
         doctree.children[-1].extend(node_list)
+
+
+class InsertToctrees(SphinxTransform):
+    """Create the toctree nodes and add it to the document.
+
+    This needs to occur at least before the ``DoctreeReadEvent`` (priority 880),
+    which triggers the `TocTreeCollector.process_doc` event (priority 500)
+    """
+
+    default_priority = 100
+
+    def apply(self, **kwargs: Any) -> None:
+        insert_toctrees(self.app, self.document)