Show file paths relative to cwd in messages (#2659)

This is useful for anyone using a terminal emulator that makes
file paths with line numbers clickable (to open an editor at that
file and line), such as VS Code or iTerm and many others.

It also matches the behavior of most UNIX tools, e.g. `git status`
or compiler error messages etc. all tend to be relative to the
current working directory.

Author: fingolfin

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * 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])
+* Show file paths in error messages relative to the current working directory instead of relative to the document root. ([#2659])
 
 ## Fixed
 
@@ -1995,6 +1996,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
+[#2659]: https://github.com/JuliaDocs/Documenter.jl/issues/2659
 [#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

src/makedocs.jl

@@ -269,6 +269,7 @@ function makedocs(; debug = false, format = HTML(), kwargs...)
     # Selectors.dispatch. This is to make sure that we pick up any new selector stages that
     # may have been added to the selector pipelines between makedocs calls.
     empty!(Selectors.selector_subtypes)
+    original_pwd[] = pwd()
     cd(document.user.root) do
         withenv(NO_KEY_ENV...) do
             Selectors.dispatch(Builder.DocumentPipeline, document)

src/utilities/utilities.jl

@@ -11,6 +11,9 @@ using .Remotes: Remote, repourl, repofile
 using .Remotes: RepoHost, RepoGithub, RepoBitbucket, RepoGitlab, RepoAzureDevOps,
     RepoUnknown, format_commit, format_line, repo_host_from_url, LineRangeFormatting
 
+const original_pwd = Ref{String}()  # for printing relative paths in error messages
+
+
 """
     @docerror(doc, tag, msg, exs...)
 
@@ -70,7 +73,9 @@ end
 
 # Pretty-printing locations
 function locrepr(file, line = nothing)
-    str = Base.contractuser(file) # TODO: Maybe print this relative the doc-root??
+    basedir = isassigned(original_pwd) ? original_pwd[] : currentdir()
+    file = abspath(file)
+    str = Base.contractuser(relpath(file, basedir))
     line !== nothing && (str = str * ":$(line.first)-$(line.second)")
     return str
 end

test/docsxref/make.jl

@@ -54,17 +54,17 @@ end
     end
     @test isnothing(captured.value)
     @test contains(
-        replace(captured.output, "src\\index" => "src/index"),
+        replace(captured.output, "\\src\\index" => "/src/index"),
         """
-        ┌ Warning: Cannot resolve @ref for md"[`AbstractSelector`](@ref)" in src/index.md.
+        ┌ Warning: Cannot resolve @ref for md"[`AbstractSelector`](@ref)" in docsxref/src/index.md.
         │ - No docstring found in doc for binding `Main.DocsReferencingMain.AbstractSelector`.
         │ - Fallback resolution in Main for `AbstractSelector` -> `Documenter.Selectors.AbstractSelector` is only allowed for fully qualified names
         """
     )
     @test contains(
-        replace(captured.output, "src\\page" => "src/page"),
+        replace(captured.output, "\\src\\page" => "/src/page"),
         """
-        ┌ Warning: Cannot resolve @ref for md"[`DocsReferencingMain.f`](@ref)" in src/page.md.
+        ┌ Warning: Cannot resolve @ref for md"[`DocsReferencingMain.f`](@ref)" in docsxref/src/page.md.
         │ - Exception trying to find docref for `DocsReferencingMain.f`: unable to get the binding for `DocsReferencingMain.f` in module Documenter.Selectors
         │ - Fallback resolution in Main for `DocsReferencingMain.f` -> `Main.DocsReferencingMain.f` is only allowed for fully qualified names
         """