Rust Docs Validation
Doctests, Rustdoc warnings, rendered docs, and docs.rs-style builds prove documentation surfaces the way users will see them. Use this mechanism when examples, public API docs, feature docs, or release-facing documentation changes.
Purpose
Build documentation the way users and docs.rs will read it. Rust documentation is often a contract for public APIs, so doc checks should prove that examples compile, feature-gated docs render, and release-facing pages can be inspected before publication.
Supported Principles
Checks
- Run doctests for public examples and Rustdoc code blocks.
cargo test --doc
- Build local docs without dependency docs when checking project output.
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
- Open rendered docs during documentation-heavy review when visual navigation matters.
cargo doc --no-deps --open
- Reproduce docs.rs-style configuration when docs.rs behavior is part of the release surface.
RUSTDOCFLAGS="--cfg docsrs -D warnings" cargo +nightly doc --no-deps --all-features
What It Catches
- Broken doctest examples.
- Missing imports or feature flags in examples.
- Rustdoc warnings promoted to release blockers.
- docs.rs-only configuration gaps.
- Navigation and rendering issues that are hard to see from Markdown or source alone.
What It Cannot Catch
Documentation builds do not prove that the explanation is helpful or that the documented behavior is the behavior users need. Pair these checks with review for claim strength, examples, and contract accuracy.