rustdoc

Generate documentation from the crate's root

$ rustdoc [src/lib.rs]

$ rustdoc [src/lib.rs] --crate-name [name]

$ rustdoc [path/to/file.md]

$ rustdoc [src/lib.rs] --out-dir [path/to/output_directory]

rustdoc [OPTIONS] <CRATE_ROOT_FILE>

-h, --help
    Prints help information for rustdoc.

-V, --version
    Prints version information for rustdoc.

-o, --output <PATH>
    Specifies the directory where the generated documentation will be written. Defaults to ./doc.

--test
    Instructs rustdoc to run all code examples found within documentation comments as tests. This is crucial for maintaining accurate documentation.

--crate-name <NAME>
    Explicitly sets the name of the crate being documented. Useful for overriding the default derived from the crate's root file.

--target <TRIPLE>
    Specifies the target triple (e.g., x86_64-unknown-linux-gnu) for which to build the documentation. This is important for cross-compilation scenarios.

--edition <EDITION>
    Sets the Rust edition (e.g., 2018, 2021) to use when compiling the crate and running doc tests.

--verbose
    Enables verbose output, showing more details about the documentation generation process, including warnings and build steps.

--markdown-css <PATH>
    Adds an additional CSS file to be used for styling the Markdown content in the generated documentation.

rustdoc is the official documentation generator for the Rust programming language. It parses Rust source code files, specifically extracting content from special documentation comments (e.g., /// for items, //! for modules/crates). These comments are written in Markdown, supporting rich text, code blocks, and links. rustdoc then renders this parsed information into a user-friendly format, most commonly HTML, providing a navigable website that details the API of a Rust crate, its modules, functions, structs, enums, traits, and more.

A key feature of rustdoc is its ability to run embedded code examples found within documentation comments as part of a "doc test" process. This ensures that the examples provided in the documentation are not only syntactically correct but also functionally accurate and up-to-date with the code, promoting high-quality, reliable documentation. While rustdoc can be invoked directly, it is most commonly used via the Rust package manager, cargo, through the cargo doc command, which simplifies its usage by handling dependency resolution and configuration automatically.

While rustdoc can be invoked directly, its full power and ease of use are typically realized when invoked via cargo doc, as cargo handles dependency resolution, compilation flags, and linking automatically. Direct invocation often requires manual management of dependencies and build flags, which can be complex for larger projects. rustdoc is tightly coupled with the Rust compiler and toolchain, meaning it requires a complete Rust installation to function.

The most common way to use rustdoc is through the cargo doc command provided by cargo, the Rust package manager. When you run cargo doc in a Rust project directory, cargo automatically finds the crate root, resolves dependencies, and passes the necessary arguments to rustdoc, simplifying the documentation generation process significantly. This seamless integration makes it easy to generate and view documentation for your projects and their dependencies.

A powerful feature of rustdoc is its ability to execute code examples embedded within documentation comments. By enclosing Rust code within a fenced code block marked with ```rust, these examples can be automatically compiled and run as part of your project's test suite when rustdoc is invoked with the --test flag (or when running cargo test). This ensures that documentation examples remain correct and functional as the codebase evolves, preventing outdated or broken examples.

Documentation comments in Rust are parsed as Markdown, allowing for rich formatting, headings, lists, links, and code blocks. rustdoc converts this Markdown into HTML. Furthermore, rustdoc provides options (e.g., --html-in-header, --markdown-css) to inject custom HTML or CSS, enabling developers to customize the appearance and behavior of their generated documentation to match project branding or specific requirements.

rustdoc has been an integral component of the Rust programming language from its early stages, evolving alongside the language itself. Its development focused on providing high-quality, easily browsable HTML documentation directly from source code, with a strong emphasis on testable code examples. The 'doc test' feature, allowing code snippets in documentation to be compiled and run as tests, was a foundational design choice, promoting accurate and up-to-date documentation. This tight integration with the language and its tooling reflects Rust's broader philosophy of prioritizing developer experience and code quality.

cargo(1), rustc(1), rustfmt(1)