cargo-rustdoc

Pass options to rustdoc

$ cargo rustdoc -- [rustdoc_options]

$ cargo rustdoc -- --warn rustdoc::[lint_name]

$ cargo rustdoc -- --allow rustdoc::[lint_name]

$ cargo rustdoc --lib

$ cargo rustdoc --bin [name]

$ cargo rustdoc --example [name]

$ cargo rustdoc --test [name]

cargo rustdoc [CARGO_OPTIONS] [-- RUSTDOC_OPTIONS...]

CARGO_OPTIONS
    These options control how cargo builds the project before running rustdoc. Common options include specifying targets, features, and build profiles.

--package , -p
    Document only the specified package(s) in the workspace.

--lib
    Document the package's library.

--bin
    Document the specified binary target. Can be used multiple times.

--example
    Document the specified example target. Can be used multiple times.

--target
    Document for the given target triple (e.g., x86_64-unknown-linux-gnu).

--release
    Document with the release profile (optimized with --opt-level=3).

--profile
    Document with the specified build profile.

--features
    Space or comma separated list of features to activate.

--all-features
    Activate all available features.

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

--open
    Open the generated documentation in a web browser after compilation.

--
    A separator indicating that all subsequent arguments are passed directly to the rustdoc executable.

RUSTDOC_OPTIONS
    These options are passed directly to the rustdoc command. They control rustdoc's behavior, such as output format, lints, or testing documentation examples.

-o

The cargo rustdoc command is a subcommand of cargo, Rust's package manager and build system. It is used to generate HTML documentation for a Rust project's API (Application Programming Interface). It leverages the rustdoc tool internally, which processes special documentation comments within Rust source code (often written in Markdown syntax) to produce a navigable set of web pages.

This command is essential for creating comprehensive and easily accessible documentation for Rust libraries and applications. It automatically compiles the project, then runs rustdoc on the compiled artifacts. The generated documentation is typically placed in the target/doc/ directory of the project, making it simple to publish or share the API documentation.

The cargo rustdoc command is not a standalone executable; it must be invoked via cargo. All arguments intended for rustdoc itself (e.g., --test, -o) must be placed after the -- separator. Forgetting the separator will cause cargo to interpret them as its own options, leading to errors. The command requires a valid Rust project with a Cargo.toml file.

By default, the generated HTML documentation is placed in the target/doc/ directory within your project. You can open the index.html file in this directory to view the documentation locally.

Documentation is generated from special comments in Rust code, typically starting with /// for items or //! for module-level documentation. These comments support Markdown for rich text formatting and code examples.

The --open flag is very convenient as it automatically launches your default web browser to display the generated documentation after the command completes successfully.

Rust has a strong emphasis on documentation, and rustdoc has been a core part of the Rust toolchain since its early days. cargo rustdoc was introduced to seamlessly integrate the documentation generation process with Rust's build system, making it as easy to generate docs as it is to compile code. This integration simplified workflows and promoted the widespread adoption of comprehensive API documentation within the Rust ecosystem.

cargo(1), rustdoc(1), rustc(1)