Support doctest testsetup (#186)

Author: felix-hilden

docs/src/about.rst

@@ -79,6 +79,12 @@ Locally defined custom block parsers in :confval:`codeautolink_custom_blocks`
 cannot be passed to Pickle, which prevents parallel Sphinx builds.
 Please consider using an importable function instead.
 
+Priority
+********
+The extension parses code blocks in the ``doctree-read`` Sphinx event.
+The priority is set to 490 to catch nodes removed by ``sphinx.ext.doctest``
+(priority 500). In other cases the priority of the extension is default.
+
 Copying code blocks
 -------------------
 If you feel like code links make copying code a bit more difficult,

docs/src/examples.rst

@@ -224,7 +224,9 @@ activating the extension::
    ]
 
 ``doctest`` and ``testcode`` blocks now work as expected.
-However, any test setup and teardown code is not taken into account.
+Code in :rst:dir:`testsetup` is considered to be the first block
+:rst:dir:`autolink-preface` before each matching test group.
+However, `skipif` is not supported.
 
 .. doctest::
 

docs/src/release_notes.rst

@@ -8,6 +8,11 @@ These release notes are based on
 sphinx-codeautolink adheres to
 `Semantic Versioning <https://semver.org>`_.
 
+Unreleased
+----------
+- Support :rst:dir:`testsetup` from ``sphinx.ext.doctest`` as another
+  type of preface (:issue:`186`)
+
 0.17.1 (2025-02-24)
 -------------------
 - Add translations via i18n (:issue:`164`)

src/sphinx_codeautolink/__init__.py

@@ -66,7 +66,7 @@ def setup(app: Sphinx):
 
     app.connect("builder-inited", state.build_inited)
     app.connect("autodoc-process-docstring", state.autodoc_process_docstring)
-    app.connect("doctree-read", state.parse_blocks)
+    app.connect("doctree-read", state.parse_blocks, priority=490)
     app.connect("env-merge-info", state.merge_environments)
     app.connect("env-purge-doc", state.purge_doc_from_environment)
     app.connect("env-updated", state.create_references)

src/sphinx_codeautolink/extension/block.py

@@ -125,6 +125,7 @@ def __init__(
         self.global_preface = global_preface
         self.file_preface = []
         self.prefaces = []
+        self.doctest_preface: dict[str, list[str]] = {}
         self.transformers = BUILTIN_BLOCKS.copy()
         self.transformers.update(custom_blocks)
         self.valid_blocks = self.transformers.keys()
@@ -198,10 +199,21 @@ def depart_section(self, node) -> None:
         """Pop latest title."""
         self.title_stack.pop()
 
-    def visit_doctest_block(self, node):
+    def visit_doctest_block(self, node: nodes.doctest_block):
         """Visit a Python doctest block."""
         return self.parse_source(node, "pycon")
 
+    def visit_comment(self, node: nodes.comment):
+        """Visit an ext.doctest setup block."""
+        if node.get("testnodetype") == "testsetup":
+            groups = node["groups"]
+            lines = [ln for c in node.children for ln in c.astext().split("\n")]
+            for g in groups:
+                if g == "*":
+                    self.doctest_preface = {"*": lines}
+                else:
+                    self.doctest_preface[g] = lines
+
     def visit_literal_block(self, node: nodes.literal_block):
         """Visit a generic literal block."""
         return self.parse_source(node, node.get("language", self.highlight_lang))
@@ -213,6 +225,15 @@ def parse_source(  # noqa: C901,PLR0912
         prefaces = self.prefaces
         self.prefaces = []
 
+        if node.get("testnodetype") == "doctest":
+            groups = node["groups"]
+            doctest_prefaces = [
+                ln
+                for g in groups
+                for ln in self.doctest_preface.get(g, self.doctest_preface.get("*", []))
+            ]
+            prefaces = doctest_prefaces + prefaces
+
         skip = self.skip
         if skip == "next":
             self.skip = None

tests/extension/ref/lexer_extdoctest_setup.txt

@@ -0,0 +1,35 @@
+test_project.bar
+tp.bar
+test.Foo
+# split
+extensions.append("sphinx.ext.doctest")
+# split
+Test project
+============
+
+.. testsetup::
+
+    import test_project
+
+.. doctest::
+
+    >>> test_project.bar()
+
+.. testsetup:: *
+
+.. doctest::
+
+    >>> test_project.Foo()
+
+.. testsetup:: thisgroup
+
+   import test_project as tp
+
+   import test_project as test
+
+.. doctest:: thisgroup
+
+    >>> tp.bar()
+    >>> test.Foo()
+
+.. automodule:: test_project

tests/extension/ref/lexer_extdoctest_setup_wrong.txt

@@ -0,0 +1,15 @@
+# split
+extensions.append("sphinx.ext.doctest")
+# split
+Test project
+============
+
+.. testsetup:: specificgroup
+
+    import test_project
+
+.. doctest::
+
+    >>> test_project.bar()
+
+.. automodule:: test_project