Skip to content

Links in API documentation #690

Closed
Closed
@dhardy

Description

@dhardy

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).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions