cargo-doc

Build the documentation for the current project and all dependencies

$ cargo [[d|doc]]

$ cargo [[d|doc]] --no-deps

$ cargo [[d|doc]] --open

$ cargo [[d|doc]] --open [[-p|--package]] [package]

cargo doc [OPTIONS]

--open
    Opens the generated documentation in your default web browser after compilation.

--no-deps
    Generates documentation only for the current package, omitting documentation for its dependencies.

--document-private-items
    Includes documentation for private items (not just public ones). Useful for internal development or debugging.

--target TRIPLE
    Builds documentation for a specific target triple (e.g., x86_64-unknown-linux-gnu).

-p SPEC, --package SPEC
    Documents only the specified package. This is useful in workspaces with multiple crates.

--features FEATURES
    Space or comma separated list of features to activate when building the documentation.

--all-features
    Activates all available features of the package and its dependencies.

--no-default-features
    Do not activate the default feature of the package.

--release
    Builds documentation with release optimizations, similar to cargo build --release.

--target-dir DIRECTORY
    Changes the directory where generated artifacts (including documentation) are placed.

--workspace
    Documents all members of the current workspace.

--lib
    Documents only the library target of the current package.

--bin NAME
    Documents only the specified binary target.

--bins
    Documents all binary targets.

--all-targets
    Documents all available targets (library, binaries, examples, tests, benches).
Note: Many common cargo options like -v (verbose) or --color are also supported.

cargo doc is a subcommand of Cargo, Rust's official build system and package manager. Its primary purpose is to generate comprehensive, browsable HTML documentation for a Rust project's crates and their dependencies. It leverages the rustdoc tool, which parses your Rust source code, specifically focusing on doc comments (lines starting with /// or //!) and public API definitions. These doc comments can contain Markdown formatting, allowing developers to write rich, readable explanations, examples, and usage guides directly within the code.

By default, cargo doc generates documentation for all public items within your crate and its dependencies, placing the output in the target/doc/ directory. The generated documentation includes an index.html file that serves as the entry point, providing navigation to all documented modules, structs, enums, functions, and traits. This command is invaluable for understanding both your own codebase and external libraries, providing an interactive, searchable interface to explore APIs and understand their usage without needing to consult external websites or manually parse source code.

cargo doc relies heavily on the rustdoc tool, which must be part of your installed Rust toolchain. By default, it only generates documentation for public items; use --document-private-items to include private ones. While doc comments support Markdown, specific syntax is required for internal links (e.g., [struct_name] for types or [module::function] for functions). Generating documentation for large projects with many dependencies can be time-consuming due to the compilation and processing involved.

Rust supports two main types of doc comments:
///: Outer doc comments, which document the item they are attached to.
//!: Inner doc comments, which document the item that contains them (e.g., a crate or module).
Both support Markdown syntax for rich formatting, code examples, and linking to other items.

The generated HTML documentation is typically placed in the target/doc/ directory within your project. Each crate gets its own subdirectory, and the main entry point is usually target/doc/your_crate_name/index.html or target/doc/index.html for the root of all documented crates (including dependencies).

While cargo doc generates documentation, it's worth noting that code examples within doc comments can also be executed as part of your test suite using cargo test. This ensures that your documentation's code examples remain correct and up-to-date, a powerful feature for maintaining high-quality documentation.

The concept of integrated documentation generation has been a cornerstone of the Rust language and its tooling from early on. rustdoc, the underlying tool for cargo doc, has continuously evolved alongside the language, adding features like improved search, theme support, and sophisticated cross-crate linking. cargo doc itself, as a core Cargo subcommand, has been available since Cargo's inception, making documentation generation a seamless and standard part of the Rust development workflow. Its stable presence underscores Rust's strong emphasis on clear, accessible, and high-quality API documentation.

cargo(1), rustdoc(1), cargo build(1), cargo test(1), rustc(1)