When fixing doctests with errors, don't overwrite [...]

Sometimes it is useful to show errors in doctests. However if those
contain stacktraces, this can be problematic as those contain line
numbers which will change over time (and often also when e.g. Julia or
some dependencies change). And sometimes it is simply desirable to
shorten the error message for other reasons.

For this reason Documenter supports replacing part of the error message
with `[...]` which can be used to omit e.g. a stacktrace while still
passing doctest checks.

However so far using Documenter's `doctest=:fix` feature would replace
all uses of `[...]` by the full error message, making it unnecessarily
tedious to update doctests in packages that use this feature.

This patch changes that by skipping doctest fixups for tests where the
reference output ends with `[...]` and otherwise matches the actual
error message as a prefix.

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * Symlinks are now followed when walking the docs directory. ([#2610])
 * PDF/LaTeX builds now throw a more informative error when `sitename` is not provided. ([#2636])
+* Fixing doctests that use `[...]` to hide part of an error message (such as a stacktrace) no longer replaces the `[...]` if the output otherwise matches ([#2642])
 
 ## Version [v1.8.1] - 2025-02-11
 

src/doctests.jl

@@ -341,7 +341,13 @@ function checkresult(sandbox::Module, result::Result, meta::Dict, doc::Documente
         if isempty(head) || !startswith(filteredstr, filteredhead) ||
                 (doc.user.doctest === :fix && filteredstr != filteredhead)
             if doc.user.doctest === :fix
-                fix_doctest(result, str, doc; prefix)
+                # special case: if everything matched prior to filtering, except for a
+                # trailing "[...]" in the reference string, then don't "fix" this but
+                # rather assume this is intentionally cutting off part of the output
+                # resp. stacktrace
+                if !(startswith(str, head) && endswith(result.output, "[...]"))
+                    fix_doctest(result, str, doc; prefix)
+                end
             else
                 report(result, str, doc)
                 @debug "Doctest metadata" meta

test/doctests/fix/broken.md

@@ -115,3 +115,8 @@ julia> a = ("a", "b", "c");
 
 julia> a
 ```
+```jldoctest
+julia> :a / :b
+ERROR: MethodError: no method matching /(::Symbol, ::Symbol)
+[...]
+```

test/doctests/fix/fixed.md

@@ -133,3 +133,8 @@ julia> a = ("a", "b", "c");
 julia> a
 ("a", "b", "c")
 ```
+```jldoctest
+julia> :a / :b
+ERROR: MethodError: no method matching /(::Symbol, ::Symbol)
+[...]
+```