From 4cc0b98a93dc7b0f3433b80f7895ee57464cf39d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20G=C3=B6ttgens?= <lars.goettgens@rwth-aachen.de>
Date: Sun, 15 Sep 2024 15:52:36 +0200
Subject: [PATCH] Add teardown phase to doctests

---
 .gitignore               |  1 +
 src/DocMeta.jl           |  6 +++++-
 src/doctests.jl          | 11 +++++++++++
 src/expander_pipeline.jl |  2 +-
 4 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index 7d8994e232..6059620b36 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,6 +16,7 @@ test/prerender/build/
 test/themes/dev/
 test/workdir/builds/
 test/quietly-logs/
+test/docsxref/
 docs/dev/
 docs/build/
 docs/build-pdf/
diff --git a/src/DocMeta.jl b/src/DocMeta.jl
index ad42abdf98..94d7bbf3b1 100644
--- a/src/DocMeta.jl
+++ b/src/DocMeta.jl
@@ -12,6 +12,7 @@ module — a special variable is created in each module that has documentation m
 # Supported metadata
 
 * `DocTestSetup`: contains the doctest setup code for doctests in the module.
+* `DocTestTeardown`: contains the doctest teardown code for doctests in the module.
 """
 module DocMeta
 import ..Documenter
@@ -26,7 +27,10 @@ const METAMODULES = Module[]
 const METATYPE = Dict{Symbol,Any}
 
 "Dictionary of all valid metadata keys and their types."
-const VALIDMETA = Dict{Symbol,Type}(:DocTestSetup => Union{Expr,Symbol})
+const VALIDMETA = Dict{Symbol,Type}(
+    :DocTestSetup => Union{Expr,Symbol},
+    :DocTestTeardown => Union{Expr,Symbol}
+)
 
 """
 """
diff --git a/src/doctests.jl b/src/doctests.jl
index 17265cf521..88c98e72f9 100644
--- a/src/doctests.jl
+++ b/src/doctests.jl
@@ -198,6 +198,17 @@ function _doctest(ctx::DocTestContext, block_immutable::MarkdownAST.CodeBlock)
                 ```
                 """)
         end
+        for expr in [get(ctx.meta, :DocTestTeardown, []); get(ctx.meta[:LocalDocTestArguments], :teardown, [])]
+            Meta.isexpr(expr, :block) && (expr.head = :toplevel)
+            try
+                Core.eval(sandbox, expr)
+            catch e
+                push!(ctx.doc.internal.errors, :doctest)
+                @error("could not evaluate expression from doctest teardown.",
+                    expression = expr, exception = e)
+                return false
+            end
+        end
         delete!(ctx.meta, :LocalDocTestArguments)
     end
     false
diff --git a/src/expander_pipeline.jl b/src/expander_pipeline.jl
index ff5bd1eeef..9e290d13e7 100644
--- a/src/expander_pipeline.jl
+++ b/src/expander_pipeline.jl
@@ -293,7 +293,7 @@ function Selectors.runner(::Type{Expanders.MetaBlocks}, node, page, doc)
         # wants to hide. We should probably warn, but it is common enough that
         # we will silently skip for now.
         if Documenter.isassign(ex)
-            if !(ex.args[1] in (:CurrentModule, :DocTestSetup, :DocTestFilters, :EditURL, :Description, :Draft, :CollapsedDocStrings))
+            if !(ex.args[1] in (:CurrentModule, :DocTestSetup, :DocTestTeardown, :DocTestFilters, :EditURL, :Description, :Draft, :CollapsedDocStrings))
                 source = Documenter.locrepr(page.source, lines)
                 @warn(
                     "In $source: `@meta` block has an unsupported " *