Support REPL softscope for Julia 1.5.

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Documenter.jl changelog
 
+## Version `v0.24.5`
+
+* ![Enhancement][badge-enhancement] ![Bugfix][badge-bugfix] Documenter now correctly emulates the "REPL softscope" (Julia 1.5) in REPL-style doctest blocks and `@repl` blocks. ([#1232][github-1232])
+
 ## Version `v0.24.4`
 
 * ![Enhancement][badge-enhancement] Change the inline code to less distracting black color in the HTML light theme. ([#1212][github-1212], [#1222][github-1222])
@@ -508,6 +512,7 @@
 [github-1216]: https://github.com/JuliaDocs/Documenter.jl/pull/1216
 [github-1222]: https://github.com/JuliaDocs/Documenter.jl/pull/1222
 [github-1223]: https://github.com/JuliaDocs/Documenter.jl/pull/1223
+[github-1232]: https://github.com/JuliaDocs/Documenter.jl/pull/1232
 
 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl
 [documentermarkdown]: https://github.com/JuliaDocs/DocumenterMarkdown.jl

src/DocTests.jl

@@ -211,6 +211,11 @@ function eval_repl(block, sandbox, meta::Dict, doc::Documents.Document, page)
         for (ex, str) in Utilities.parseblock(input, doc, page; keywords = false, raise=false)
             # Input containing a semi-colon gets suppressed in the final output.
             result.hide = REPL.ends_with_semicolon(str)
+            if VERSION >= v"1.5.0-DEV.178"
+                # Use the REPL softscope for REPL jldoctests,
+                # see https://github.com/JuliaLang/julia/pull/33864
+                ex = REPL.softscope!(ex)
+            end
             (value, success, backtrace, text) = Utilities.withoutput() do
                 Core.eval(sandbox, ex)
             end

src/Expanders.jl

@@ -608,6 +608,11 @@ function Selectors.runner(::Type{REPLBlocks}, x, page, doc)
     for (ex, str) in Utilities.parseblock(x.code, doc, page; keywords = false)
         buffer = IOBuffer()
         input  = droplines(str)
+        if VERSION >= v"1.5.0-DEV.178"
+            # Use the REPL softscope for REPLBlocks,
+            # see https://github.com/JuliaLang/julia/pull/33864
+            ex = REPL.softscope!(ex)
+        end
         (value, success, backtrace, text) = Utilities.withoutput() do
             cd(page.workdir) do
                 Core.eval(mod, ex)

test/doctests/doctests.jl

@@ -211,6 +211,15 @@ rfile(filename) = joinpath(@__DIR__, "stdouts", filename)
         @test success
         @test is_same_as_file(output, rfile("32.stdout"))
     end
+
+    if VERSION >= v"1.5.0-DEV.178"
+        # Julia 1.5 REPL softscope,
+        # see https://github.com/JuliaLang/julia/pull/33864
+        run_makedocs(["softscope.md"]) do result, success, backtrace, output
+            @test success
+            @test is_same_as_file(output, rfile("1.stdout"))
+        end
+    end
 end
 
 using Documenter.DocTests: remove_common_backtrace

test/doctests/src/softscope.md

@@ -0,0 +1,52 @@
+Julia 1.5's REPL softscope
+
+```
+julia> s = 0 # global
+0
+
+julia> for i = 1:10
+           t = s + i # new local `t`
+           s = t # assign global `s`
+       end
+
+julia> s # global
+55
+
+julia> @isdefined(t) # global
+false
+```
+
+```
+julia> code = """
+       s = 0 # global
+       for i = 1:10
+           t = s + i # new local `t`
+           s = t # new local `s` with warning
+       end
+       s, # global
+       @isdefined(t) # global
+       """;
+
+julia> include_string(Main, code)
+┌ Warning: Assignment to `s` in soft scope is ambiguous because a global variable by the same name exists: `s` will be treated as a new local. Disambiguate by using `local s` to suppress this warning or `global s` to assign to the existing global variable.
+└ @ string:4
+ERROR: LoadError: UndefVarError: s not defined
+```
+
+```jldoctest
+s = 0 # global
+for i = 1:10
+    t = s + i # new local `t`
+    s = t # new local `s` with warning
+end
+s, # global
+@isdefined(t) # global
+
+# output
+
+┌ Warning: Assignment to `s` in soft scope is ambiguous because a global variable by the same name exists: `s` will be treated as a new local. Disambiguate by using `local s` to suppress this warning or `global s` to assign to the existing global variable.
+└ @ ~/dev/Documenter/test/doctests/doctests.jl:3
+ERROR: UndefVarError: s not defined
+Stacktrace:
+[...]
+```