Closed
Description
Many of the links in our API documentation are currently simple relative paths.
- For links within the same crate this works everywhere but is fragile (if the documented item moves into or out of a sub-module).
- For links to other Rand crates this works for our hosted documentation but not on docs.rs.
- For links to items from other crates which are not dependencies but instead linked as a suggested alternative or usage, it may be confusing where to find that (e.g. see chacha etc. documentation? #646).
Thanks to RFC 1946 we should be able to improve this.
To address the above, I think we should:
- Revise existing relative links to use Rust paths instead of file paths, according to the RFC
- Decide how to handle links to non-dependencies
- Add notes to the Book doc contributions guide
Part of this needs additional discussion: how do we link to things which are not dependencies correctly? Examples:
SeedableRng
mentionsrand::FromEntropy
StdRng
referencesrand_hc::Hc128Rng
andrand_chacha::ChaChaRng
Note that we don't currently appear to have a technical solution to reliably link to all these, except with blunt absolute or relative links (see rust-lang/docs.rs#204).
Metadata
Metadata
Assignees
Labels
No labels