Add a prefix when replacing for doctest=:fix

CHANGELOG.md

@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * A fully qualified `@ref` link now resolves in `Main` as well, in addition to `CurrentModule`. For any package whose docstrings are included in the documentation, as long as that package is loaded in `make.jl`, fully qualified `@ref` links to docstrings in the package will work from anywhere. This simplifies, e.g., linking between docstrings for packages that use sub-modules. ([#2470])
 
+### Fixed
+
+* Doctest fixing functionality handles another edge case. ([#2303], [#2378])
+
 
 ## Version [v1.3.0] - 2024-03-01
 
@@ -1782,6 +1786,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2288]: https://github.com/JuliaDocs/Documenter.jl/issues/2288
 [#2293]: https://github.com/JuliaDocs/Documenter.jl/issues/2293
 [#2300]: https://github.com/JuliaDocs/Documenter.jl/issues/2300
+[#2303]: https://github.com/JuliaDocs/Documenter.jl/issues/2303
 [#2306]: https://github.com/JuliaDocs/Documenter.jl/issues/2306
 [#2307]: https://github.com/JuliaDocs/Documenter.jl/issues/2307
 [#2308]: https://github.com/JuliaDocs/Documenter.jl/issues/2308
@@ -1803,6 +1808,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2373]: https://github.com/JuliaDocs/Documenter.jl/issues/2373
 [#2374]: https://github.com/JuliaDocs/Documenter.jl/issues/2374
 [#2375]: https://github.com/JuliaDocs/Documenter.jl/issues/2375
+[#2378]: https://github.com/JuliaDocs/Documenter.jl/issues/2378
 [#2394]: https://github.com/JuliaDocs/Documenter.jl/issues/2394
 [#2406]: https://github.com/JuliaDocs/Documenter.jl/issues/2406
 [#2408]: https://github.com/JuliaDocs/Documenter.jl/issues/2408
@@ -1817,6 +1823,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2459]: https://github.com/JuliaDocs/Documenter.jl/issues/2459
 [#2460]: https://github.com/JuliaDocs/Documenter.jl/issues/2460
 [#2461]: https://github.com/JuliaDocs/Documenter.jl/issues/2461
+[#2470]: https://github.com/JuliaDocs/Documenter.jl/issues/2470
 [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/doctests.jl

@@ -52,6 +52,11 @@
     end
 end
 
+mutable struct MutablePrefix
+    content :: String
+    MutablePrefix() = new("")
+end
+
 function _doctest(page::Documenter.Page, doc::Documenter.Document)
     ctx = DocTestContext(page.source, doc) # FIXME
     ctx.meta[:CurrentFile] = page.source
@@ -202,24 +207,31 @@
 # Doctest evaluation.
 
 mutable struct Result
-    block  :: MutableMD2CodeBlock # The entire code block that is being tested.
-    input  :: String # Part of `block.code` representing the current input.
-    output :: String # Part of `block.code` representing the current expected output.
-    file   :: String # File in which the doctest is written. Either `.md` or `.jl`.
-    value  :: Any        # The value returned when evaluating `input`.
-    hide   :: Bool       # Semi-colon suppressing the output?
-    stdout :: IOBuffer   # Redirected stdout/stderr gets sent here.
-    bt     :: Vector     # Backtrace when an error is thrown.
+    block      :: MutableMD2CodeBlock # The entire code block that is being tested.
+    raw_input  :: String # Part of `block.code` representing the current input.
+    input      :: String # Part of `block.code` representing the current input
+                         # without leading repl prompts and spaces.
+    output     :: String # Part of `block.code` representing the current expected output.
+    file       :: String # File in which the doctest is written. Either `.md` or `.jl`.
+    value      :: Any        # The value returned when evaluating `input`.
+    hide       :: Bool       # Semi-colon suppressing the output?
+    stdout     :: IOBuffer   # Redirected stdout/stderr gets sent here.
+    bt         :: Vector     # Backtrace when an error is thrown.
 
     function Result(block, input, output, file)
-        new(block, input, rstrip(output, '\n'), file, nothing, false, IOBuffer())
+        new(block, input, input, rstrip(output, '\n'), file, nothing, false, IOBuffer())
+    end
+    function Result(block, raw_input, input, output, file)
+        new(block, raw_input, input, rstrip(output, '\n'), file, nothing, false, IOBuffer())
     end
 end
 
+
 function eval_repl(block, sandbox, meta::Dict, doc::Documenter.Document, page)
     src_lines = Documenter.find_block_in_file(block.code, meta[:CurrentFile])
-    for (input, output) in repl_splitter(block.code)
-        result = Result(block, input, output, meta[:CurrentFile])
+    (prefix, split) = repl_splitter(block.code)
+    for (raw_input, input, output) in split
+        result = Result(block, raw_input, input, output, meta[:CurrentFile])
         for (ex, str) in Documenter.parseblock(input, doc, page; keywords = false, raise=false)
             # Input containing a semi-colon gets suppressed in the final output.
             @debug "Evaluating REPL line from doctest at $(Documenter.locrepr(result.file, src_lines))" unparsed_string = str parsed_expression = ex
@@ -239,7 +251,7 @@
             # don't evaluate further if there is a parse error
             isa(ex, Expr) && ex.head === :error && break
         end
-        checkresult(sandbox, result, meta, doc)
+        checkresult(sandbox, result, meta, doc; prefix)
     end
 end
 
@@ -288,7 +300,7 @@
 end
 
 # Regex used here to replace gensym'd module names could probably use improvements.
-function checkresult(sandbox::Module, result::Result, meta::Dict, doc::Documenter.Document)
+function checkresult(sandbox::Module, result::Result, meta::Dict, doc::Documenter.Document; prefix::MutablePrefix=MutablePrefix())
     sandbox_name = nameof(sandbox)
     mod_regex = Regex("(Main\\.)?(Symbol\\(\"$(sandbox_name)\"\\)|$(sandbox_name))[,.]")
     mod_regex_nodot = Regex(("(Main\\.)?$(sandbox_name)"))
@@ -312,12 +324,19 @@
         # to check that manually with `isempty`.
         if isempty(head) || !startswith(filteredstr, filteredhead)
             if doc.user.doctest === :fix
-                fix_doctest(result, str, doc)
+                fix_doctest(result, str, doc; prefix)
             else
                 report(result, str, doc)
                 @debug "Doctest metadata" meta
                 push!(doc.internal.errors, :doctest)
             end
+        else
+            # Prefix was not modified, unless output was different.
+            prefix.content *= result.raw_input*"\n"
+            if str != ""
+                prefix.content *= str * "\n"
+            end
+            prefix.content *= "\n"
         end
     else
         value = result.hide ? nothing : result.value # `;` hides output.
@@ -332,12 +351,19 @@
         )
         if filteredstr != filteredoutput
             if doc.user.doctest === :fix
-                fix_doctest(result, str, doc)
+                fix_doctest(result, str, doc; prefix)
             else
                 report(result, str, doc)
                 @debug "Doctest metadata" meta
                 push!(doc.internal.errors, :doctest)
             end
+        else
+            # Prefix was not modified, unless output was different.
+            prefix.content *= result.raw_input*"\n"
+            if str != ""
+                prefix.content *= str * "\n"
+            end
+            prefix.content *= "\n"
         end
     end
     return nothing
@@ -448,7 +474,7 @@
         """, diff, _file=result.file, _line=line)
 end
 
-function fix_doctest(result::Result, str, doc::Documenter.Document)
+function fix_doctest(result::Result, str, doc::Documenter.Document; prefix::MutablePrefix=MutablePrefix())
     code = result.block.code
     filename = Base.find_source_file(result.file)
     # read the file containing the code block
@@ -470,7 +496,8 @@
     write(io, content[1:prevind(content, first(codeidx))])
     # next look for the particular input string in the given code block
     # make a regex of the input that matches leading whitespace (for multiline input)
-    rinput = "\\h*" * replace(Documenter.regex_escape(result.input), "\\n" => "\\n\\h*")
+    composed = prefix.content * result.raw_input
+    rinput = replace(Documenter.regex_escape(composed), "\\n" => "\\n\\h*")
     r = Regex(rinput)
     inputidx = findfirst(r, code)
     if inputidx === nothing
@@ -480,6 +507,11 @@
     # construct the new code-snippet (without indent)
     # first part: everything up until the last index of the input string
     newcode = code[1:last(inputidx)]
+    prefix.content = newcode * "\n"
+    if str != ""
+        prefix.content *= str * "\n"
+    end
+    prefix.content *= "\n"
     isempty(result.output) && (newcode *= '\n') # issue #772
     # second part: the rest, with the old output replaced with the new one
     if result.output == ""
@@ -488,7 +520,11 @@
         newcode *= str
         newcode *= code[nextind(code, last(inputidx)):end]
     else
-        newcode *= replace(code[nextind(code, last(inputidx)):end], result.output => str, count = 1)
+        if str == ""
+            newcode *= replace(code[nextind(code, last(inputidx)):end], result.output * "\n" => str, count = 1)
+        else
+            newcode *= replace(code[nextind(code, last(inputidx)):end], result.output => str, count = 1)
+        end
     end
     # replace internal code block with the non-indented new code, needed if we come back
     # looking to replace output in the same code block later
@@ -511,31 +547,40 @@
 function repl_splitter(code)
     lines  = split(string(code, "\n"), '\n')
     input  = String[]
+    raw_inputs = String[]
     output = String[]
+    prefix = MutablePrefix()
     buffer = IOBuffer() # temporary buffer for doctest inputs and outputs
+    raw_input_buffer = IOBuffer()
     found_first_prompt = false
     while !isempty(lines)
         line = popfirst!(lines)
         prompt = match(PROMPT_REGEX, line)
         # We allow comments before the first julia> prompt
-        !found_first_prompt && startswith(line, '#') && continue
+        if !found_first_prompt && startswith(line, '#')
+            prefix.content *= line * "\n"
+            continue
+        end
         if prompt === nothing
             source = match(SOURCE_REGEX, line)
             if source === nothing
                 savebuffer!(input, buffer)
+                savebuffer!(raw_inputs, raw_input_buffer)
                 println(buffer, line)
                 takeuntil!(PROMPT_REGEX, buffer, lines)
             else
                 println(buffer, source[1])
+                println(raw_input_buffer, line)
             end
         else
             found_first_prompt = true
             savebuffer!(output, buffer)
             println(buffer, prompt[1])
+            println(raw_input_buffer, line)
         end
     end
     savebuffer!(output, buffer)
-    zip(input, output)
+    return prefix, zip(raw_inputs, input, output)
 end
 
 function savebuffer!(out, buf)

test/doctests/fix/broken.md

@@ -78,3 +78,40 @@ julia> 1 + 2
 
 julia> 3 + 4
 ```
+```jldoctest
+julia> a = (1,2)
+
+julia> a
+```
+```jldoctest
+# Leading comment
+julia> a
+ERROR: UndefVarError: `a` not defined
+
+julia> a = Int64[1,2]
+2-element Vector{Int64}:
+ 1
+ 2
+
+julia> b
+
+julia> a
+2-element Vector{Int64}:
+ 2
+
+julia> a;
+1
+
+julia> b;
+
+julia> a = Int64[3,4];
+
+julia> a
+ 3
+ 4
+```
+```jldoctest
+julia> a = ("a", "b", "c");
+
+julia> a
+```

test/doctests/fix/fixed.md

@@ -87,3 +87,46 @@ julia> 1 + 2
 julia> 3 + 4
 7
 ```
+```jldoctest
+julia> a = (1,2)
+(1, 2)
+
+julia> a
+(1, 2)
+```
+```jldoctest
+# Leading comment
+julia> a
+ERROR: UndefVarError: `a` not defined
+
+julia> a = Int64[1,2]
+2-element Vector{Int64}:
+ 1
+ 2
+
+julia> b
+ERROR: UndefVarError: `b` not defined
+
+julia> a
+2-element Vector{Int64}:
+ 1
+ 2
+
+julia> a;
+
+julia> b;
+ERROR: UndefVarError: `b` not defined
+
+julia> a = Int64[3,4];
+
+julia> a
+2-element Vector{Int64}:
+ 3
+ 4
+```
+```jldoctest
+julia> a = ("a", "b", "c");
+
+julia> a
+("a", "b", "c")
+```

test/doctests/fix/tests.jl

@@ -45,8 +45,15 @@ function test_doctest_fix(dir)
     @debug "Running doctest/fix doctests with doctest=true"
     @quietly makedocs(sitename="-", modules = [Foo], source = srcdir, build = builddir)
 
-    # also test that we obtain the expected output
-    @test normalize_line_endings(index_md) == normalize_line_endings(joinpath(@__DIR__, "fixed.md"))
+    # Load desired results and adapt to various Julia versions:
+    md_result = normalize_line_endings(joinpath(@__DIR__, "fixed.md"))
+    if VERSION < v"1.7"
+        # Error output is different in 1.6, so we adapt by having a separate correct file.
+        md_result = replace(md_result, r"UndefVarError: `([^`]*)` not defined" => s"UndefVarError: \1 not defined")
+    end
+
+    # test that we obtain the expected output
+    @test normalize_line_endings(index_md) == md_result
     @test normalize_line_endings(src_jl) == normalize_line_endings(joinpath(@__DIR__, "fixed.jl"))
 end