rustdoc: add a way to link relative to the root of the docs

[vext01]

In a recent documentation change, we were unable to create a link to a function in std and had to resort to linking to online documentation.

@eddyb described it best:

../std won't work in core::hint/std::hint and ../../std won't work in test

Thus the link checker can't be satisfied.

For more info, see:
#62891 (comment)

[eddyb]

cc @QuietMisdreavus @GuillaumeGomez

Is there some other syntax that could be used to get the same effect, regardless of where it's used?

But also, could paths be interpreted relative to where the item being documented is defined, as supposed to where it's reexported from?

[mati865]

Maybe something like here https://github.com/rust-lang/rust/pull/61926/files?

EDIT: Explained in #61926 (comment)

[RalfJung]

Does that work reliably? Last time I tried to use it I was told not to. ;) I have also needed this when linking to the reference, where that would not work. Having a variable that expands to the root seems most general.

[vext01]

Having a variable that expands to the root seems most general.

Sounds good to me.

[GuillaumeGomez]

For this kind of problems, we use intra-links. No need to put the full path, just the type.

[RalfJung]

@GuillaumeGomez does that mean links like crate::vec::Vec are working properly these days?

Also see my question above: what if I want to link to the reference? There always is a reference "next to" the std docs, so I could use something like ../../reference/behavior-considered-undefined.html, but that relies on relative paths again.

[GuillaumeGomez]

For the reference, please use a full url. No miraculous solution in there... :-/

[RalfJung]

@GuillaumeGomez you didn't answer my question -- are links like crate::vec::Vec considered stable so that we can actually start using them in the docs? The last I heard is that this is experimental and should not be used.

This is just biting us again in #66379, where we want to link to the ptr module docs. And we want to link to a particular section of those docs. Is crate::ptr#safety a thing?

For the reference, please use a full url. No miraculous solution in there... :-/

There's an easy solution: provide a variable that expands to the root of the docs. Then for the reference we could do $DOCROOT/reference/behavior-considered-undefined.html.

[GuillaumeGomez]

They are already used in the std docs so you can consider them "stable". Also the anchor PR has been merged.

[RalfJung]

They are already used in the std docs so you can consider them "stable".

Great!

What remains of this issue is the case where one wants to link to the reference (or another "associated book") from a doc-comment that is included on several different folder depths. This is the one place that I am aware of where we are still forced to use absolute paths, and it could be fixed by having some way to tell rustdoc that a path is relative to the root of the docs.