Error on duplicate ref a bit too eager and too uninformative?

[kellertuer]

A few days ago my CI suddenly started to fail, see e.g. the 66(!) errors at

https://github.com/JuliaManifolds/Manopt.jl/actions/runs/19391210207/job/55484919743#step:8:1970

For me an error message like

┌ Error: Cannot resolve @ref for md"[`Stepsize`](@ref)" in docs/src/solvers/NelderMead.md.
│ - Header with slug 'Stepsize' is not unique in docs/src/solvers/NelderMead.md.
└ @ Documenter ~/.julia/packages/Documenter/yVko2/src/utilities/utilities.jl:47

when the corresponding Markdown file

https://github.com/JuliaManifolds/Manopt.jl/blob/master/docs/src/solvers/NelderMead.md

does not even contain that. Sure the rendered page

https://manoptjl.org/stable/solvers/NelderMead/#Manopt.NelderMeadState

refers to the type, but also has only one such reference and that works correctly.

Sure in strict mode, errors is what one usually asks for, but why does this error? It is unique!

I lost quite some time until on Slack I was hinted to #2787. While that is a bug fix maybe
a) a more informative message (maybe mention the alternatives is could not distinguish?)
b) at least for a version a warning and only starting in 1.17 an error would have been nice? Cf #2751 where even a thrown warning being turned into an error is discussed as breaking. Here a not-even-warning was directly turned into erroring (tremendously).

Turns out, the fix is just this commit JuliaManifolds/Manopt.jl@105de42

one page had a header which I gave the id stepsize (accidentally probably) and I had two headers of subsections with that title. So 3 errors (that I wished would be warnings first) would be ok.

Maybe this is a bit over reporting now?

That the two pages with stepsize headers should error if one refers to Stepsize and it is unclear whether it should be the type or the section. But outside of that page - and for all 66 occurrences of the (in all places) correctly resolved link to the type?

[fingolfin]

Thank you for filing this issue, and once more sorry for the pain this caused you.

So, some thoughts on what went on: the error pointed to docs/src/solvers/NelderMead.md which was not helpful, because the string Stepsize does not appear in this file at all!

Instead, it appears in one of the docstrings getting included on that page:

## State

```@docs
    NelderMeadState
```

So we really want the error message to point to src/documentation_glossary.jl:502.

This is actually a concern for other errors, too, and has also bitten myself quite hard in the past for other reasons... sometimes all you know is that "some docstring somewhere has an error" and then have fun finding it :-/.

Unfortunately right now this is non-trivial to implement, because we simply don't keep track of the origin of the things we included into the .md file :-(. Hence I opened issue #2826 with a plan forward: we need to better keep track of the origin of docstrings. If we did that, it would allow us to improve the error here, and in other cases.

OK but back to your report: also the text "Cannot resolve @ref" is not too helpful. I think we also show this message when the label does not exist at all. Instead the error should make it clear that the label is ambiguous.

Even better would be if we then listed the locations of the identical labels.

Finally, we could suggest a solution

So something like that would be a step up:

┌ Error: Ambiguous @ref for md"[`Stepsize`](@ref)" in src/documentation_glossary.jl:502.
│ - Header with slug 'Stepsize' is not unique in src/documentation_glossary.jl:502.
│   The following places all declare header with slug `Stepsize`:
│   - ‎docs/src/plans/stepsize.md‎:1
│   - docs/src/solvers/proximal_gradient_method.md‎:31
│   - ‎docs/src/solvers/vectorbundle_newton.md‎:20
│   To resolve the issue, adjust these to use unique slugs,
│   by assigning an explicitly `@id`.
└ @ Documenter ~/.julia/packages/Documenter/yVko2/src/utilities/utilities.jl:47

[kellertuer]

Thanks your steps sound good.

One thing to add: The error reported, that stepsise was ambiguous also appeared on pages like gradient descent.md where there is no (own) Stepsize section and formerly the only link was the Stepsize type. That is what I was referring to as “over reporting”; but I do see the that would require the Headers from your 2&3 ambiguous reports would need to “localise” in some sense. So maybe there is no way around the 60+ errors I got (besides that having those as a warning for a while would have been nice.

Thanks for opening the issue about the origin, that would be really great to have, I already spent quite some time tracking down several errors (not only this one) due to missing origins.