🎓 A1Learner
🔍

Rust Cargo Doc Options

cargo doc is the Cargo command that builds documentation pages. One flag builds only the crate itself.

Only your own crate

Skip the dependency pages while you write — it is much faster:

cargo doc --no-deps

Private items too

Useful on a team, when the readers are the authors:

cargo doc --document-private-items

Make warnings fail the build

Broken doc links become errors, so a CI job catches them:

RUSTDOCFLAGS="-D warnings" cargo doc

Search by types, not names

In the search bar of any generated site, this finds functions taking a usize and returning a Vec:

usize -> Vec

Example

fn main() {
    println!("cargo doc               -> docs for your crate and its dependencies");
    println!("cargo doc --open        -> build the docs and open them in a browser");
    println!("cargo doc --no-deps     -> build only your crate, much faster");
    println!("cargo doc --document-private-items -> include private items too");
}

Key points

  • cargo doc builds pages for your crate and its dependencies into target/doc — the front page is target/doc/<crate>/index.html
  • Use cargo doc --open to build the pages and open the front page in your browser in one step
  • Use cargo rustdoc -- <flags> to hand extra flags to rustdoc for your own crate only, for example cargo rustdoc -- --document-private-items
  • Use cargo doc --all-features when items behind feature switches should all appear.
  • A plain run documents only the features that are on.
  • Tell docs.rs what to build for your published crate with a [package.metadata.docs.rs] table in Cargo.toml: all-features, a features list, and rustdoc-args are read there, not by your local cargo doc
  • Narrow a name search on a generated site with a kind prefix.
  • struct: , fn: and trait: each search only that kind of item.
  • cargo doc builds documentation pages, and its flags choose what gets built.

In this example, the program is a small cheat sheet you can run. Each line pairs a command with what it does. Plain cargo doc documents dependencies as well as your crate. --open adds the browser. --no-deps drops the dependency pages for speed, and --document-private-items adds the private items that a normal run leaves out.

Note

cargo doc is a friendly front end.

Underneath, it runs the rustdoc tool once per crate, filling in each crate name and the dependency paths for you.

Try it Yourself

Edit the code, then press Run.

Running is simulated · Rust Playground

Exercise

While writing, you want the fastest docs build that covers only your own crate. Which command fits?