Better error message when no doc found

[fingolfin]

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.

[mortenpi]

Saying that it's in a docstring should be doable (i.e. we should have that information). Line numbers are trickier though, since, if I remember correctly, the Markdown parser does not store such information. We could potentially try to grep for it though, like we do when updating doctest outputs.

[fingolfin]

So when we initially parse these docstrings, we do know where they are from. Inside of Selectors.runner(::Type{Expanders.AutoDocsBlocks}, all this information is present.

When we then later try to resolve the @ref in docsxref, we are just looking at a MarkdownAST.Link and indeed have not enough information.

But at some point that MarkdownAST.Link gets created starting from a docstring; at that point we should still be able to know where the docstring came from. So we "just" need to associate this information to the Link. That may not be possible "inside" the Link; but we could just keep a globale Dict or IdDict or WeakKeyDict, which maps the newly created nodes (such as this Link node) back to their sources.

[fingolfin]

BTW the error string looks different these days; the following comes from a local hack.

┌ Error: Cannot resolve @ref for md"[Documenter.better_helper](@ref)" in docs/src/lib/internals/doctests.md.
│ - No docstring found in doc for binding `Documenter.better_helper`.
└ @ Documenter ~/Projekte/Julia/packages/JuliaDocs/Documenter.jl/src/utilities/utilities.jl:47

[mortenpi]

But at some point that MarkdownAST.Link gets created starting from a docstring; at that point we should still be able to know where the docstring came from. So we "just" need to associate this information to the Link. That may not be possible "inside" the Link; but we could just keep a globale Dict or IdDict or WeakKeyDict, which maps the newly created nodes (such as this Link node) back to their sources.

Not sure off the top of my head what the correct, so to speak, solution here is, but we can also create custom node types for MarkdownAST, so we could have more metadata, if need be.