77

I'm building a Rust library and want to give it some polish. In the rustdoc, I'd sometimes like to link to other parts of the library within the docs, e.g. fns, traits or structs. What is the official syntax for this?

2

5 Answers 5

101

As of Rust 1.48, you can now rely on RFC 1946. This adds the concept of intra-documentation links. This allows using Rust paths as the URL of a link:

  1. [Iterator](std::iter::Iterator)
  2. [Iterator][iter], and somewhere else in the document: [iter]: std::iter::Iterator
  3. [Iterator], and somewhere else in the document: [Iterator]: std::iter::Iterator

The RFC also introduces "Implied Shortcut Reference Links". This allows leaving out the link reference, which is then inferred automatically.

  1. [std::iter::Iterator], without having a link reference definition for Iterator anywhere else in the document
  2. [`std::iter::Iterator`], without having a link reference definition for Iterator anywhere else in the document (same as previous style but with back ticks to format link as inline code)

As a concrete example, this source code:

//! Check out [ExampleStruct], especially [this
//! method](ExampleStruct::foo), but [the trait method][trait] is also
//! cool. There is also [an enum variant you can
//! use](nested::ExampleEnum::Beta).
//!
//! [trait]: ExampleTrait::bar

pub struct ExampleStruct;

impl ExampleStruct {
    pub fn foo(&self) {}
}

pub trait ExampleTrait {
    fn bar();
}

pub mod nested {
    pub enum ExampleEnum {
        Alpha,
        Beta,
    }
}

Produces this documentation:

example generated documentation

Specifically, this HTML is generated:

<p>Check out <a href="../doc_link_example/struct.ExampleStruct.html" title="ExampleStruct">ExampleStruct</a>, especially <a href="../doc_link_example/struct.ExampleStruct.html#method.foo">this method</a>, but <a href="../doc_link_example/trait.ExampleTrait.html#tymethod.bar">the trait method</a> is also cool. There is also <a href="../doc_link_example/nested/enum.ExampleEnum.html#Beta.v">an enum variant you can use</a>.</p>
7
  • For absolute module paths, [foo](crate::stuff::thing) seems to work.
    – rodrigocfd
    Dec 4, 2020 at 18:10
  • @rodrigocfd yes, that's listed in the documentation I've linked.
    – Shepmaster
    Dec 4, 2020 at 18:11
  • Is there a way to reference a different crate in the same workspace? E.g. I have a macros crate and the actual lib crate and I'd like to have a link from the documentation in the macros crate to the relevant code using the macro in the lib crate. In the macros crate, trying to link to [my_lib_crate::module::Symbol] warns of a broken link; trying [../my_lib_crate::module::Symbol] doesn't recognize this as a link. Any way to achieve this? Nov 18, 2021 at 11:52
  • @OrenBen-Kiki I'd expect that you'd need to import the lib crate from the macros crate and then that would allow you to reference it.
    – Shepmaster
    Nov 23, 2021 at 15:44
  • Yes, one can have one-directional links this way if one crate uses another; but you can't have two-way links because that would cause a circular dependency between the crates. An option that works is for the lib crate to pub use the macros crate and re-export all the macros, and document everything in the lib crate. But there seems to be no way to freely link in both directions between two crates in a workspace...? Nov 24, 2021 at 8:37
46

As of Rust 1.48, Rustdoc now supports direct intra-doc links.


Pre Rust 1.48:

Rustdoc seems to generate mostly deterministic filenames for constituent elements of a crate. Therefore if you have an enum named Complex you can generally link to it using:

[Complex](enum.Complex.html)

Similarly a struct called Point would look like:

[Point](struct.Point.html)

This should carry over to most definitions (fn, trait, and so on).

For referencing elements of a crate at different nesting levels, you can use relative paths (where each module is its own folder):

[Point](../model/struct.Point.html)

or use absolute paths:

[Point](/crate_name/model/struct.Point.html)

More of these "conventions", including anchors for specific fields, etc., can be deduced if one builds docs (cargo doc --no-deps --open) and navigates to the field or item they want and takes note of the URL. Remember that only pub items are published to docs.

3
  • 1
    Relative paths work as well for objects in other modules: [Point](../point/struct.Point.html)
    – Lanklaas
    Nov 8, 2019 at 9:20
  • 8
    The URL [Point](/crate_name/model/struct.Point.html) seems not to work anymore, at least when I open docs on my filesystem. It links to file:///crate_name/.... Feb 4, 2020 at 21:15
  • 1
    This answer is outdated. Though this still works, please see shepmaster's answer for an easier up-to-date approach: stackoverflow.com/a/53504254/353178
    – mkirk
    Oct 21, 2020 at 19:57
10

If one wants to link some specific part of a struct e.g., a method named foo in the same struct (using stable rust, not nightly)

[foo](#method.foo)

or if it is in another struct

[foo](struct.OtherStruct.html#method.foo)
1

In Rust 1.49 nightly it works (1.48 stable not released yet):

  • [super::structs::WebApiResponse]
  • [mycrate::structs::WebApiResponse]

etc.

Read here

-1

Since the documentation is written in Markdown, just use the Markdown syntax for Hyperlinks; i.e.

[anchor text](URL)

Also, take a look at this: https://doc.rust-lang.org/book/documentation.html

1
  • 23
    This doesn't really answer the question, because I don't think there's a way to figure out the URL.
    – kralyk
    Jul 6, 2016 at 10:57

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.