Rustdoc is the official documentation generator for the Rust programming language. It parses Rust source code and generates HTML documentation, making it easy to understand and navigate your projects. This tool is essential for any Rust developer looking to create clear, comprehensive, and accessible API documentation.

Basic Rustdoc Usage

The fundamental command to generate documentation for a Rust project involves specifying the entry point of your crate. For a library, this is typically src/lib.rs.

# Generate HTML documentation from a Rust project
rustdoc src/lib.rs

Customizing Output and Appearance

Rustdoc offers several options to tailor the generated documentation to your needs, including specifying the output directory, including private items, and applying custom themes.

# Generate documentation with a custom output directory
rustdoc src/lib.rs --output target/doc

# Include private items in the generated documentation
rustdoc src/lib.rs --document-private-items

# Specify the HTML theme to use for the documentation
rustdoc src/lib.rs --theme path/to/theme.css

Advanced Documentation Generation

Beyond basic HTML, Rustdoc can generate documentation in JSON format, set custom crate names, and integrate external resources for richer documentation.

# Generate JSON format documentation instead of HTML
rustdoc src/lib.rs --output-format json

# Set document title
rustdoc src/lib.rs --crate-name my_crate

# Add an external HTML page to the documentation
rustdoc src/lib.rs --html-in-header path/to/header.html

# Add CSS file to customize the documentation style
rustdoc src/lib.rs --html-includes css/path/print.css

# Link to documentation for dependencies hosted on external URLs
rustdoc src/lib.rs --extern-html-root-url dep-name=url

# Generate lint warnings for missing items
rustdoc src/lib.rs --warn missing-docs

Key Rustdoc Features

Rustdoc is a powerful tool that supports various features to enhance your documentation experience. It allows for the inclusion of markdown files, custom CSS, and linking to external documentation sources. This ensures that your Rust projects are well-documented and easy for others to understand and use.

Further Resources

For more in-depth information on Rustdoc and its capabilities, refer to the official Rust documentation:

• Rustdoc Book
• Rustc Command-Line Arguments (for rustdoc options)