Skip to content

Commit c754edc

Browse files
fingolfinfingolfin
authored
Add locrepr methods, improve path generation (#2803)
* Add locrepr(::Document, ::Page) method: This has higher level info and thus has an easier time getting paths right. * Improve locrepr for pages * Add locrepr(::DCtx) * Print line ranges in a few more errors
1 parent fefe54d commit c754edc

File tree

6 files changed

+50
-36
lines changed

6 files changed

+50
-36
lines changed

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1515
* Page category is removed from the search index and now everything is in section category. ([#2762], [#2413])
1616
* Changed the docstring block accordions from a custom implementation to HTML details+summary tag. ([#2772], [#2773])
1717
* Improved the search tokenizer and custom trimmer to improve search results. ([#1457], [#2114], [#2744])
18+
* Improved several warning/error messages to (more accurately) report the location (filename, line range) in which the warning/error originated. ([#2803])
1819

1920
### Fixed
2021

@@ -2178,6 +2179,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
21782179
[#2774]: https://github.com/JuliaDocs/Documenter.jl/issues/2774
21792180
[#2787]: https://github.com/JuliaDocs/Documenter.jl/issues/2787
21802181
[#2792]: https://github.com/JuliaDocs/Documenter.jl/issues/2792
2182+
[#2803]: https://github.com/JuliaDocs/Documenter.jl/issues/2803
21812183
[JuliaLang/julia#36953]: https://github.com/JuliaLang/julia/issues/36953
21822184
[JuliaLang/julia#38054]: https://github.com/JuliaLang/julia/issues/38054
21832185
[JuliaLang/julia#39841]: https://github.com/JuliaLang/julia/issues/39841

‎src/cross_references.jl‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ function local_links!(node::MarkdownAST.Node, meta, page, doc)
8080
if node.element isa MarkdownAST.Image
8181
@docerror(
8282
doc, :cross_references,
83-
"invalid local image: path missing in $(Documenter.locrepr(page.source))",
83+
"invalid local image: path missing in $(Documenter.locrepr(doc, page))",
8484
link = node
8585
)
8686
return
@@ -90,7 +90,7 @@ function local_links!(node::MarkdownAST.Node, meta, page, doc)
9090
elseif Sys.iswindows() && ':' in path
9191
@docerror(
9292
doc, :cross_references,
93-
"invalid local link/image: colons not allowed in paths on Windows in $(Documenter.locrepr(page.source))",
93+
"invalid local link/image: colons not allowed in paths on Windows in $(Documenter.locrepr(doc, page))",
9494
link = node
9595
)
9696
return
@@ -101,7 +101,7 @@ function local_links!(node::MarkdownAST.Node, meta, page, doc)
101101
if startswith(path, "..")
102102
@docerror(
103103
doc, :cross_references,
104-
"invalid local link/image: path pointing to a file outside of build directory in $(Documenter.locrepr(page.source))",
104+
"invalid local link/image: path pointing to a file outside of build directory in $(Documenter.locrepr(doc, page))",
105105
link = node
106106
)
107107
return
@@ -116,7 +116,7 @@ function local_links!(node::MarkdownAST.Node, meta, page, doc)
116116
if !isempty(fragment)
117117
@docerror(
118118
doc, :cross_references,
119-
"invalid local image: path contains a fragment in $(Documenter.locrepr(page.source))",
119+
"invalid local image: path contains a fragment in $(Documenter.locrepr(doc, page))",
120120
link = node
121121
)
122122
end
@@ -128,7 +128,7 @@ function local_links!(node::MarkdownAST.Node, meta, page, doc)
128128
else
129129
@docerror(
130130
doc, :cross_references,
131-
"invalid local link/image: file does not exist in $(Documenter.locrepr(page.source))",
131+
"invalid local link/image: file does not exist in $(Documenter.locrepr(doc, page))",
132132
link = node
133133
)
134134
return
@@ -314,7 +314,7 @@ function xref(node::MarkdownAST.Node, meta, page, doc)
314314
# finalizer
315315
if xref_unresolved(node)
316316
md_str = strip(Markdown.plain(_link_node_as_md(node)))
317-
msg = "Cannot resolve @ref for md$(repr(md_str)) in $(Documenter.locrepr(page.source))."
317+
msg = "Cannot resolve @ref for md$(repr(md_str)) in $(Documenter.locrepr(doc, page))."
318318
if (length(errors) > 0)
319319
msg *= ("\n" * join([string("- ", err) for err in errors], "\n"))
320320
end
@@ -375,7 +375,7 @@ function namedxref(node::MarkdownAST.Node, slug, meta, page, doc, errors)
375375
page = doc.blueprint.pages[pagekey]
376376
node.element = Documenter.PageLink(page, anchor_label(anchor))
377377
else
378-
push!(errors, "Header with slug '$slug' is not unique in $(Documenter.locrepr(page.source)).")
378+
push!(errors, "Header with slug '$slug' is not unique in $(Documenter.locrepr(doc, page)).")
379379
end
380380
return
381381
end
@@ -396,7 +396,7 @@ function docsxref(node::MarkdownAST.Node, code, meta, page, doc, errors)
396396
modules = [Main]
397397
end
398398
for (attempt, mod) in enumerate(modules)
399-
docref = find_docref(code, mod, page)
399+
docref = find_docref(code, mod, page, doc)
400400
if haskey(docref, :error)
401401
# We'll bail if the parsing of the docref wasn't successful
402402
msg = "Exception trying to find docref for `$code`: $(docref.error)"
@@ -432,7 +432,7 @@ function docsxref(node::MarkdownAST.Node, code, meta, page, doc, errors)
432432
return
433433
end
434434

435-
function find_docref(code, mod, page)
435+
function find_docref(code, mod, page, doc)
436436
# Parse the link text and find current module.
437437
keyword = Symbol(strip(code))
438438
local ex
@@ -443,7 +443,7 @@ function find_docref(code, mod, page)
443443
ex = Meta.parse(code)
444444
catch err
445445
isa(err, Meta.ParseError) || rethrow(err)
446-
return (error = "unable to parse the reference `$code` in $(Documenter.locrepr(page.source)).", exception = nothing)
446+
return (error = "unable to parse the reference `$code` in $(Documenter.locrepr(doc, page)).", exception = nothing)
447447
end
448448
end
449449

@@ -464,7 +464,7 @@ function find_docref(code, mod, page)
464464
typesig = Core.eval(mod, Documenter.DocSystem.signature(ex, rstrip(code)))
465465
catch err
466466
return (
467-
error = "unable to evaluate the type signature for `$code` in $(Documenter.locrepr(page.source)) in module $(mod)",
467+
error = "unable to evaluate the type signature for `$code` in $(Documenter.locrepr(doc, page)) in module $(mod)",
468468
exception = (err, catch_backtrace()),
469469
)
470470
end
@@ -534,7 +534,7 @@ function issue_xref(node::MarkdownAST.Node, num, meta, page, doc, errors)
534534
# Update issue links starting with a hash, but only if our Remote supports it
535535
issue_url = isnothing(doc.user.remote) ? nothing : Remotes.issueurl(doc.user.remote, num)
536536
if isnothing(issue_url)
537-
push!(errors, "unable to generate issue reference for '[`#$num`](@ref)' in $(Documenter.locrepr(page.source)).")
537+
push!(errors, "unable to generate issue reference for '[`#$num`](@ref)' in $(Documenter.locrepr(doc, page)).")
538538
else
539539
node.element.destination = issue_url
540540
end

‎src/docchecks.jl‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -138,15 +138,15 @@ function footnotes(doc::Document)
138138
for (id, (ids, bodies)) in orphans
139139
# Multiple footnote bodies.
140140
if bodies > 1
141-
@docerror(doc, :footnote, "footnote '$id' has $bodies bodies in $(locrepr(page.source)).")
141+
@docerror(doc, :footnote, "footnote '$id' has $bodies bodies in $(locrepr(doc, page)).")
142142
end
143143
# No footnote references for an id.
144144
if ids === 0
145-
@docerror(doc, :footnote, "unused footnote named '$id' in $(locrepr(page.source)).")
145+
@docerror(doc, :footnote, "unused footnote named '$id' in $(locrepr(doc, page)).")
146146
end
147147
# No footnote bodies for an id.
148148
if bodies === 0
149-
@docerror(doc, :footnote, "no footnotes found for '$id' in $(locrepr(page.source)).")
149+
@docerror(doc, :footnote, "no footnotes found for '$id' in $(locrepr(doc, page)).")
150150
end
151151
end
152152
end

‎src/expander_pipeline.jl‎

Lines changed: 19 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ function expand(doc::Documenter.Document)
5959
Selectors.dispatch(Expanders.ExpanderPipeline, node, page, doc)
6060
expand_recursively(node, page, doc)
6161
end
62-
pagecheck(page)
62+
pagecheck(doc, page)
6363
clear_modules!(page.globals.meta)
6464
end
6565
return
@@ -85,10 +85,10 @@ function expand_recursively(node, page, doc)
8585
end
8686

8787
# run some checks after expanding the page
88-
function pagecheck(page)
88+
function pagecheck(doc, page)
8989
# make sure there is no "continued code" lingering around
9090
if haskey(page.globals.meta, :ContinuedCode) && !isempty(page.globals.meta[:ContinuedCode])
91-
@warn "code from a continued @example block unused in $(Documenter.locrepr(page.source))."
91+
@warn "code from a continued @example block unused in $(Documenter.locrepr(doc, page))."
9292
end
9393
return
9494
end
@@ -341,7 +341,7 @@ function Selectors.runner(::Type{Expanders.MetaBlocks}, node, page, doc)
341341
# we will silently skip for now.
342342
if Documenter.isassign(ex)
343343
if !(ex.args[1] in (:CurrentModule, :DocTestSetup, :DocTestTeardown, :DocTestFilters, :EditURL, :Description, :Draft, :CollapsedDocStrings, :ShareDefaultModule))
344-
source = Documenter.locrepr(page.source, lines)
344+
source = Documenter.locrepr(doc, page, lines)
345345
@warn(
346346
"In $source: `@meta` block has an unsupported " *
347347
"keyword argument: $(ex.args[1])",
@@ -353,7 +353,7 @@ function Selectors.runner(::Type{Expanders.MetaBlocks}, node, page, doc)
353353
@docerror(
354354
doc, :meta_block,
355355
"""
356-
failed to evaluate `$(strip(str))` in `@meta` block in $(Documenter.locrepr(page.source, lines))
356+
failed to evaluate `$(strip(str))` in `@meta` block in $(Documenter.locrepr(doc, page, lines))
357357
```$(x.info)
358358
$(x.code)
359359
```
@@ -431,7 +431,7 @@ function Selectors.runner(::Type{Expanders.DocsBlocks}, node, page, doc)
431431
@docerror(
432432
doc, :docs_block,
433433
"""
434-
unable to get the binding for '$(strip(str))' in `@docs` block in $(Documenter.locrepr(page.source, lines)) from expression '$(repr(ex))' in module $(curmod)
434+
unable to get the binding for '$(strip(str))' in `@docs` block in $(Documenter.locrepr(doc, page, lines)) from expression '$(repr(ex))' in module $(curmod)
435435
```$(x.info)
436436
$(x.code)
437437
```
@@ -446,7 +446,7 @@ function Selectors.runner(::Type{Expanders.DocsBlocks}, node, page, doc)
446446
@docerror(
447447
doc, :docs_block,
448448
"""
449-
undefined binding '$(binding)' in `@docs` block in $(Documenter.locrepr(page.source, lines))
449+
undefined binding '$(binding)' in `@docs` block in $(Documenter.locrepr(doc, page, lines))
450450
```$(x.info)
451451
$(x.code)
452452
```
@@ -463,7 +463,7 @@ function Selectors.runner(::Type{Expanders.DocsBlocks}, node, page, doc)
463463
@docerror(
464464
doc, :docs_block,
465465
"""
466-
duplicate docs found for '$(strip(str))' in `@docs` block in $(Documenter.locrepr(page.source, lines))
466+
duplicate docs found for '$(strip(str))' in `@docs` block in $(Documenter.locrepr(doc, page, lines))
467467
```$(x.info)
468468
$(x.code)
469469
``` $(DocSystem.public_unexported_msg(apistatus))
@@ -486,7 +486,7 @@ function Selectors.runner(::Type{Expanders.DocsBlocks}, node, page, doc)
486486
@docerror(
487487
doc, :docs_block,
488488
"""
489-
no docs found for '$(strip(str))' in `@docs` block in $(Documenter.locrepr(page.source, lines))
489+
no docs found for '$(strip(str))' in `@docs` block in $(Documenter.locrepr(doc, page, lines))
490490
```$(x.info)
491491
$(x.code)
492492
```
@@ -534,7 +534,7 @@ function Selectors.runner(::Type{Expanders.AutoDocsBlocks}, node, page, doc)
534534
elseif ex.args[1] in (:Modules, :Order, :Pages, :Public, :Private)
535535
fields[ex.args[1]] = Core.eval(curmod, ex.args[2])
536536
else
537-
source = Documenter.locrepr(page.source, lines)
537+
source = Documenter.locrepr(doc, page, lines)
538538
@warn(
539539
"In $source: `@autodocs` block has an unsupported " *
540540
"keyword argument: $(ex.args[1])",
@@ -544,7 +544,7 @@ function Selectors.runner(::Type{Expanders.AutoDocsBlocks}, node, page, doc)
544544
@docerror(
545545
doc, :autodocs_block,
546546
"""
547-
failed to evaluate `$(strip(str))` in `@autodocs` block in $(Documenter.locrepr(page.source, lines))
547+
failed to evaluate `$(strip(str))` in `@autodocs` block in $(Documenter.locrepr(doc, page, lines))
548548
```$(x.info)
549549
$(x.code)
550550
```
@@ -575,7 +575,7 @@ function Selectors.runner(::Type{Expanders.AutoDocsBlocks}, node, page, doc)
575575
@docerror(
576576
doc, :autodocs_block,
577577
"""
578-
@autodocs ($(Documenter.locrepr(page.source, lines))) encountered a bad docstring binding '$(binding)'
578+
@autodocs ($(Documenter.locrepr(doc, page, lines))) encountered a bad docstring binding '$(binding)'
579579
```$(x.info)
580580
$(x.code)
581581
```
@@ -649,7 +649,7 @@ function Selectors.runner(::Type{Expanders.AutoDocsBlocks}, node, page, doc)
649649
@docerror(
650650
doc, :autodocs_block,
651651
"""
652-
duplicate docs found for '$(object.binding)' in $(Documenter.locrepr(page.source, lines))
652+
duplicate docs found for '$(object.binding)' in $(Documenter.locrepr(doc, page, lines))
653653
```$(x.info)
654654
$(x.code)
655655
``` $(DocSystem.public_unexported_msg(apistatus))
@@ -674,7 +674,7 @@ function Selectors.runner(::Type{Expanders.AutoDocsBlocks}, node, page, doc)
674674
@docerror(
675675
doc, :autodocs_block,
676676
"""
677-
'@autodocs' missing 'Modules = ...' in $(Documenter.locrepr(page.source, lines))
677+
'@autodocs' missing 'Modules = ...' in $(Documenter.locrepr(doc, page, lines))
678678
```$(x.info)
679679
$(x.code)
680680
```
@@ -715,7 +715,7 @@ function Selectors.runner(::Type{Expanders.EvalBlocks}, node, page, doc)
715715
@docerror(
716716
doc, :eval_block,
717717
"""
718-
failed to evaluate `@eval` block in $(Documenter.locrepr(page.source))
718+
failed to evaluate `@eval` block in $(Documenter.locrepr(doc, page, lines))
719719
```$(x.info)
720720
$(x.code)
721721
```
@@ -732,7 +732,7 @@ function Selectors.runner(::Type{Expanders.EvalBlocks}, node, page, doc)
732732
# objects, like Paragraph.
733733
@docerror(
734734
doc, :eval_block, """
735-
Invalid type of object in @eval in $(Documenter.locrepr(page.source))
735+
Invalid type of object in @eval in $(Documenter.locrepr(doc, page, lines))
736736
```$(x.info)
737737
$(x.code)
738738
```
@@ -864,7 +864,7 @@ function Selectors.runner(::Type{Expanders.ExampleBlocks}, node, page, doc)
864864
@docerror(
865865
doc, :example_block,
866866
"""
867-
failed to run `@example` block in $(Documenter.locrepr(page.source, lines))
867+
failed to run `@example` block in $(Documenter.locrepr(doc, page, lines))
868868
```$(x.info)
869869
$(x.code)
870870
```
@@ -1015,10 +1015,11 @@ function Selectors.runner(::Type{Expanders.SetupBlocks}, node, page, doc)
10151015
end
10161016
catch err
10171017
bt = Documenter.remove_common_backtrace(catch_backtrace())
1018+
lines = Documenter.find_block_in_file(x.code, page.source)
10181019
@docerror(
10191020
doc, :setup_block,
10201021
"""
1021-
failed to run `@setup` block in $(Documenter.locrepr(page.source))
1022+
failed to run `@setup` block in $(Documenter.locrepr(doc, page, lines))
10221023
```$(x.info)
10231024
$(x.code)
10241025
```

‎src/html/HTMLWriter.jl‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -709,6 +709,12 @@ struct DCtx
709709
) = new(dctx.ctx, navnode, droplinks, footnotes)
710710
end
711711

712+
function Documenter.locrepr(dctx::DCtx, lines = nothing)
713+
doc = dctx.ctx.doc
714+
page = dctx.navnode.page
715+
return Documenter.locrepr(dctx.ctx.doc, dctx.ctx.page, lines)
716+
end
717+
712718
function SearchRecord(ctx::HTMLContext, navnode; fragment = "", title = nothing, category = "page", text = "")
713719
page_title = mdflatten_pagetitle(DCtx(ctx, navnode))
714720
if title === nothing
@@ -2477,7 +2483,7 @@ function domify(dctx::DCtx, node::Node, f::MarkdownAST.FootnoteDefinition)
24772483
# TODO: this could be rearranged such that we push!() the DOM here into .footnotes, rather
24782484
# than the Node objects.
24792485
if isnothing(dctx.footnotes)
2480-
@error "Invalid nested footnote definition in $(Documenter.locrepr(dctx.navnode.page))" f.id
2486+
@error "Invalid nested footnote definition in $(Documenter.locrepr(dctx))" f.id
24812487
else
24822488
push!(dctx.footnotes, node)
24832489
end

‎src/utilities/utilities.jl‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,14 +72,19 @@ function find_block_in_file(code, file)
7272
end
7373

7474
# Pretty-printing locations
75-
function locrepr(file, line = nothing)
75+
function locrepr(file::String, lines::Union{Nothing, Pair{Int, Int}} = nothing)
7676
basedir = isassigned(original_pwd) ? original_pwd[] : currentdir()
7777
file = abspath(file)
7878
str = Base.contractuser(relpath(file, basedir))
79-
line !== nothing && (str = str * ":$(line.first)-$(line.second)")
79+
lines !== nothing && (str = str * ":$(lines.first)-$(lines.second)")
8080
return str
8181
end
8282

83+
function locrepr(doc, page, lines::Union{Nothing, Pair{Int, Int}} = nothing)
84+
file = joinpath(doc.user.root, page.source)
85+
return locrepr(file, lines)
86+
end
87+
8388
# Directory paths.
8489

8590
"""

0 commit comments

Comments
 (0)