trixi-framework / trixi-framework/Trixi.jl

Figure out why some macros cannot be `@ref`'d in Documenter.jl

Open
#1,475 0 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
Julia
Stars
731
Forks
167
Avg merge
2d 18h
Merged PRs (30d)
25

Description

Following up on #1468 and #1473: Some macro calls - it was confirmed for `@autoinfiltrate` and `@threaded` fail with a documentation build error such as
```
[...]
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
┌ Error: no doc found for reference '[`@threaded`](@ref)' in src/visualization.md.
└ @ Documenter.CrossReferences ~/.julia/packages/Documenter/H5y27/src/Utilities/Utilities.jl:32
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
ERROR: LoadError: `makedocs` encountered an error (:cross_references). Terminating build before rendering.
Stacktrace:
[1-5] ⋮ internal
@ Base, Documenter.Builder, Documenter.Utilities.Selectors, Base.Filesystem, Unknown
[6] makedocs(; debug::Bool, format::Documenter.Writers.HTMLWriter.HTML, kwargs::Base.Pairs{Symbol, Any, …})
@ Documenter ~/.julia/packages/Documenter/H5y27/src/Documenter.jl:272
[7] top-level scope
@ ~/hackathon/Trixi.jl/docs/make.jl:75
[8] include(fname::String)
@ Base.MainInclude ./client.jl:478
Use `err` to retrieve the full stack trace.
in expression starting at /Users/hpcschlo/hackathon/Trixi.jl/docs/make.jl:75
```
(see linked GH Actions log for more details). It seems to be either a user failure in how we use Documenter.jl (if yes, I don't see how) or a bug in Documenter.jl (again, I couldn't tell where).

Contributor guide

Open the contributing guide

Research direction

Start with docs/make.jl and the @ref uses in src/visualization.md, then reproduce the documented cross-reference error with the Trixi.jl documentation build. Inspect the Documenter.jl cross-reference handling to determine whether the macro usage or Documenter.jl is responsible; done means the affected macro references build successfully or the cause is clearly documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
julia
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.