Rust Reference ยท Tools
cargo doc
Reference for cargo doc: build HTML documentation for your crate and its dependencies, open it, document private items and treat doc warnings as errors.
cargo doc runs rustdoc on your package and every dependency, and writes HTML into target/doc. The pages are built from the /// and //! doc comments in your source, plus the signatures and trait implementations the compiler knows about, so even an undocumented crate gets a browsable API listing.
The command is a thin wrapper: it works out the right rustdoc flags and extern crates for each member of the build. For what goes inside the comments (Markdown, intra-doc links, doctests) see rustdoc. This page is a read-only command reference; the examples show the kind of code the generated pages describe.
$ cargo doc --no-deps --open
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Syntax
cargo doc [options]
| Name | Description |
|---|---|
--open |
Open the crate's front page in your browser when the build finishes. |
--no-deps |
Document only your workspace members, not dependencies. Much faster. |
--document-private-items |
Include private items, useful for internal documentation. |
--workspace, -p name |
Document every workspace member, or one package. |
--features, --all-features |
Build docs with those features enabled. |
--lib, --bins |
Restrict to the library or binary targets. |
--target-dir, --release |
Choose the output location and profile. |
Warnings: broken intra-doc links and invalid code blocks are reported as rustdoc:: lints. Deny them in CI with RUSTDOCFLAGS="-D warnings" cargo doc --no-deps.
Usage notes
- The output starts at
target/doc/<crate_name>/index.html; hyphens in the package name become underscores. - Documentation for dependencies is built from your lock file, so the pages match the versions you actually compile.
cargo docdoes not run doctests.cargo test(orcargo test --doc) does that.- Binary-only packages are documented too, but docs for binaries are usually only useful with
--document-private-items. - To show feature requirements on items, nightly users enable
doc_auto_cfg; docs.rs builds with its own flags set in[package.metadata.docs.rs]. - Publishing a crate to crates.io triggers a docs.rs build automatically. See cargo publish and package.
- Search is built in: press
Sor/on any generated page.