trixi-framework / trixi-framework/Trixi.jl
Figure out why some macros cannot be `@ref`'d in Documenter.jl
- 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
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