Reduce memory usage when using many pages with examples (#2662)

Author: fingolfin

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## Changed
 
 * Now the cursor remain focused on search box even after selecting the filter. ([#2410])
+* The "sandbox" modules used for running the code (doctests, examples) are now cleared after a page has been processed, allowing the garbage collector to reclaim memory and therefore reducing memory usage. ([#2640], [#2662])
 
 ## Fixed
 
@@ -1985,6 +1986,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2624]: https://github.com/JuliaDocs/Documenter.jl/issues/2624
 [#2629]: https://github.com/JuliaDocs/Documenter.jl/issues/2629
 [#2636]: https://github.com/JuliaDocs/Documenter.jl/issues/2636
+[#2640]: https://github.com/JuliaDocs/Documenter.jl/issues/2640
 [#2642]: https://github.com/JuliaDocs/Documenter.jl/issues/2642
 [#2646]: https://github.com/JuliaDocs/Documenter.jl/issues/2646
 [#2648]: https://github.com/JuliaDocs/Documenter.jl/issues/2648
@@ -1993,6 +1995,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2652]: https://github.com/JuliaDocs/Documenter.jl/issues/2652
 [#2656]: https://github.com/JuliaDocs/Documenter.jl/issues/2656
 [#2658]: https://github.com/JuliaDocs/Documenter.jl/issues/2658
+[#2662]: https://github.com/JuliaDocs/Documenter.jl/issues/2662
 [JuliaLang/julia#36953]: https://github.com/JuliaLang/julia/issues/36953
 [JuliaLang/julia#38054]: https://github.com/JuliaLang/julia/issues/38054
 [JuliaLang/julia#39841]: https://github.com/JuliaLang/julia/issues/39841

src/expander_pipeline.jl

@@ -1,5 +1,26 @@
 # Defines node "expanders" that transform nodes from the parsed markdown files.
 
+# helper for "cleaning up" content of modules to enable garbage collection.
+# See also <https://github.com/JuliaDocs/Documenter.jl/issues/2640>.
+function clear_module!(M::Module)
+    # we need `invokelatest` here for Julia >= 1.12 (or 1.13?)
+    for name in Base.invokelatest(names, M, all = true)
+        if !isconst(M, name)
+            @eval M $name = $nothing
+        end
+    end
+    return
+end
+
+function clear_modules!(d::Dict{Symbol, Any})
+    for (k, v) in d
+        startswith(String(k), "__atexample__") || continue
+        v isa Module && clear_module!(v)
+    end
+    GC.gc()
+    return
+end
+
 function expand(doc::Documenter.Document)
     priority_pages = filter(doc.user.expandfirst) do src
         if src in keys(doc.blueprint.pages)
@@ -23,6 +44,7 @@ function expand(doc::Documenter.Document)
             expand_recursively(node, page, doc)
         end
         pagecheck(page)
+        clear_modules!(page.globals.meta)
     end
     return
 end

test/clear_module/src/index.md

@@ -0,0 +1,23 @@
+# Testing
+
+We set up some test code and create an object with a finalizer.
+
+```@setup
+@eval Main finalizer_count = [0]
+
+mutable struct MyMutableStruct
+  bar
+  function MyMutableStruct(bar)
+      x = new(bar)
+      finalizer(x) do y
+        Main.finalizer_count[1] += 1
+      end
+  end
+end
+
+a = MyMutableStruct(1)
+```
+
+Once Documenter is finished processing this page, it should remove the
+reference to the object `a` and a subsequent garbage collection should free
+it, which we can later test by observing the value of `Main.finalizer_count`.

test/clear_module/tests.jl

@@ -0,0 +1,15 @@
+using Documenter
+using Test
+
+const pages = [
+    "Home" => "index.md",
+]
+
+makedocs(sitename = "Test", pages = pages, doctest = true)
+
+@testset "clear_modules!" begin
+    # force a full GC
+    GC.gc(true)
+    # check that the finalizer was run
+    @test Main.finalizer_count[1] == 1
+end

test/runtests.jl

@@ -94,6 +94,10 @@ end
     @info "Building workdir/tests.jl"
     @quietly include("workdir/tests.jl")
 
+    # A simple build verifying that sandbox modules are cleared at the end of each page
+    @info "Building clear_module/tests.jl"
+    @quietly include("clear_module/tests.jl")
+
     # Passing a writer positionally (https://github.com/JuliaDocs/Documenter.jl/issues/1046)
     @test_throws MethodError makedocs(sitename = "", HTML())