Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Links in API documentation #690

Closed
2 of 3 tasks
dhardy opened this issue Jan 10, 2019 · 0 comments
Closed
2 of 3 tasks

Links in API documentation #690

dhardy opened this issue Jan 10, 2019 · 0 comments

Comments

@dhardy
Copy link
Member

dhardy commented Jan 10, 2019

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 mentions rand::FromEntropy
  • StdRng references rand_hc::Hc128Rng and rand_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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant