Support relative links between crates?

[dhardy]

Example: Rand has multiple crates in the same repo.

We have been using relative links between the crates, e.g.:

[`BlockRng`]: ../../../rand_core/block/struct.BlockRng.html

If we build doc with cargo doc --all, these links work fine locally. They do not work on docs.rs (e.g. block BlockRng here).

Is there a good solution for this? We'd prefer not to use absolute links to docs.rs. We have documentation here which resolves the cross-linking just fine.

[dhardy]

It would be nice to have a solution to this.

One option might be to add redirect URLs for companion crates, e.g. docs.rs/rand/0.6.0/rand_core might redirect to docs.rs/rand_core/0.3.0/rand_core. These "companion crates" could be discovered by analysing broken links reported by cargo deadlinks or could be configured in docs.rs's crate metadata.

[newpavlov]

Good news! It seems we already can do it as a side effect of rust-lang/rfcs#1946 (tracking issue). See this test crate, in the docstring it simply has [`RngCore`], which correctly generates the cross-crate link to rand_core thanks to internal private (!) use rand_core::RngCore;.

One restriction is that link should be for the crate dependency, in other words IIUC we can't (yet) link rand::Rng from rand_core.

[dhardy]

We suggest the following syntax:

rustdoc --extern-base-url="regex=https://docs.rs/regex/0.2.2/regex/" [...]

(From here.) Sounds like a solution, but not currently implemented; sounds like instead these cross-crate links are automatically generated but only for dependencies.

Sometimes we refer in the documentation to things not used in the code (to suggest alternatives); this can even be from a crate which is not a dependency. This problem was already mentioned here but I am not aware of a solution.

Anyway, it sounds like this solves around 98% of our cross-crate doc linking problems.

[QuietMisdreavus]

@newpavlov Intra-doc links is supposed to work off all the use statements in the doc comment's scope, so the fact that that use rand_core::RngCore was private yet still worked was by-design.

It also looks like the introduction of the --extern-html-root-url flag (rust-lang/rust#51384, added here in #243) also helped out intra-doc links! I didn't realize that at the time when implementing it, but i'm glad it worked out like that. I have some ideas for putting items in-scope for just rustdoc, but for now you can use absolute paths ([`RngCore`](rand_core::RngCore)) if you want to avoid having an "unused" import.

[dhardy]

Thanks @QuietMisdreavus. So --extern-html-root-url rand=https://docs.rs/rand/0.6.0 should work for rand_core (which doesn't actually depend on rand)?

Then the question is how to specify this flag — for our own build (by Travis) this is easy enough, but for the documentation built and hosted on docs.rs it is not.

So we can maybe refer to rand::rngs::adapter::ReseedingRng in the rand_core docs, and add --extern-html-root-url rand=http://rust-random.github.io/rand to our Travis build, however the linking will only work for docs hosted on our github.io page unless docs.rs can be convinced to pass a similar flag.

[QuietMisdreavus]

It's possible to ask docs.rs to send custom flags (see the "Metadata for custom builds" on this page) but i don't think it will work, because the information of what's inside the crate will not be available to the name resolver that we use to look it up. That information needs to be available to the compiler (which is why local use statements work), but it won't be aware of downstream crates.

[dhardy]

Oh I see; a link to rand_chacha::ChaChaRng can't simply guess where within the rand_chacha crate this symbol should be (since it doesn't know this is a struct, and that it's not a pub use'd item). Any other ideas how this could work?

---

We've also discussed linking to a crate's top-level API documentation, e.g. rand_chacha — but it would be nice if we didn't have to hard-code links to docs.rs so that e.g. links within our github.io-hosted docs would work (rand_chacha) as well as links for local documentation builds. Any ideas?

[QuietMisdreavus]

Oh I see; a link to rand_chacha::ChaChaRng can't simply guess where within the rand_chacha crate this symbol should be (since it doesn't know this is a struct, and that it's not a pub use'd item). Any other ideas how this could work?

Doing it "properly" probably requires a big refactoring internal to the compiler (being able to load a downstream crate's metadata without creating circular dependencies), though so does the other major change i want for this feature (saving resolver scopes when compiling so re-exported docs can resolve intra-doc links in their original location), so it can come up in that discussion too.

We've also discussed linking to a crate's top-level API documentation, e.g. rand_chacha — but it would be nice if we didn't have to hard-code links to docs.rs so that e.g. links within our github.io-hosted docs would work (rand_chacha) as well as links for local documentation builds. Any ideas?

Sadly, there's no good way to get this to work as-is. You'll have to hard-code a link somewhere, whether as a relative link (and break docs.rs) or as an absolute link to somewhere that's hosting it (and make offline docs awkward). I don't know a good way around it. Rocket's docs have the same problem, because they like to link the base library's docs to the "contrib" library, which is a downstream crate.

[jyn514]

See also rust-lang/rust#74481.