JuliaDocs/Documenter.jl

Better error message when no doc found

Open

#1,996 opened on Dec 14, 2022

View on GitHub
 (4 comments) (0 reactions) (0 assignees)Julia (513 forks)batch import
Topic: UsabilityType: Enhancementhelp wanted

Repository metrics

Stars
 (910 stars)
PR merge metrics
 (Avg merge 16d 9h) (3 merged PRs in 30d)

Description

Today we had this error in our CI pipeline that puzzled us for quite some time:

Error: no doc found for reference '[`is_pure`](@ref)' in src/abelian/structural.md

We eventually figured it out; but what would have helped us a lot would have been if there had been also a line number (or at least a rough range) within src/abelian/structural.md where the error was triggered.

In this case, the @ref was not in the .md file but rather was from a docstring. So it would have been extremely helpful to be told that, too: i.e. something like "from docstring of function Foo in file src/bar.jl:123" or whatever.

Contributor guide

Research direction
Locate where the error message 'no doc found for reference' is generated in Documenter.jl. Then add context such as the line number in the source file or the name of the docstring and its file. Look at the code path that processes cross references.
Tech stack
julia
Domain
documentation
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
Half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
JuliaDocumenter.jl basics
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
65