With Cargo, what does `cargo doc --no-deps` build, and why does a broken intra-doc link pass `cargo clippy` and `cargo test` unnoticed?
answer
- only rustdoc resolves doc links
- target/doc, your packages only
- warn-by-default rustdoc lints
- [lints.rustdoc] or RUSTDOCFLAGS
- docs.rs reads package.metadata
basics
~20 scargo doc --no-deps runs rustdoc on the selected packages only and writes HTML to target/doc. Intra-doc links are resolved only by rustdoc, and broken_intra_doc_links only warns, so CI must run cargo doc with that lint denied.
solid answer
~40 s`cargo doc` documents the selected packages *and* all their dependencies into `target/doc`; `--no-deps` skips the dependencies, which is what CI usually wants. Generation is cumulative, so pages from earlier runs remain until `cargo clean --doc`. A link such as ``[`TileId::parse`]`` is resolved only by rustdoc: `cargo build`, `cargo clippy` and `cargo test --doc` never check it, and rustdoc's `broken_intra_doc_links` is warn-by-default, so even `cargo doc` exits 0. Make it fail with `broken_intra_doc_links = "deny"` under `[lints.rustdoc]`, with `RUSTDOCFLAGS="-D warnings"`, or with `CARGO_BUILD_WARNINGS=deny` (Cargo 1.97 and later), which covers `cargo doc` too. docs.rs builds with its own settings from `[package.metadata.docs.rs]` (`all-features`, `features`, `targets`, `rustdoc-args` such as `--cfg docsrs`), a table Cargo itself ignores.
code
toml · 17 lines[package]
name = "tiles"
version = "0.1.0"
edition = "2024"
[features]
serde = []
[dependencies]
itoa = "1"
[lints.rustdoc]
broken_intra_doc_links = "deny"
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]go deeper
Recall that cargo doc writes HTML to target/doc and that --no-deps skips the dependencies.
Explain that only rustdoc resolves intra-doc links, that broken_intra_doc_links is warn-by-default, and the three ways to make it fail.
Show a CI step that keeps published docs honest (cargo doc --no-deps with rustdoc warnings denied) and how you preview docs.rs output with --cfg docsrs and --all-features.
Treat documentation as part of a library's interface: a lead decides which rustdoc lints gate a merge and whether missing_docs is enforced on public items.
## What `cargo doc` produces `cargo doc` runs **rustdoc**, Rust's documentation generator, through Cargo: - Output goes to `target/doc`, one directory per crate plus a shared search index; `--open` opens the result in a browser. - By default it documents the selected packages **and all their dependencies**, so `target/doc` also gains pages for every crate in the graph. - `--no-deps` documents only the selected packages. In a workspace, `--workspace` or `-p` select which members. - Library and binary targets are documented by default, and for a binary target private items are included as if `--document-private-items` had been passed. - Generation is **cumulative**: pages from earlier runs, including dependency pages from a run without `--no-deps`, stay in `target/doc` until `cargo clean --doc` removes them. ## Why broken links slip through An intra-doc link is a doc-comment link written as a Rust path, such as ``[`TileId::parse`]``; how to write them is a matter for the language's documentation-comment rules. What matters here is **which command checks them**: 1. rustc does not resolve the links inside doc comments, so `cargo build` and `cargo check` cannot see a bad link. 2. `cargo clippy` with its default groups does not resolve intra-doc links either; in the test crate it finished with no warning. 3. `cargo test --doc` hands code blocks to rustdoc to compile and run as doctests, but it does not resolve links; the run reported `test result: ok`. 4. Only rustdoc, run by `cargo doc`, resolves links, and its `broken_intra_doc_links` lint is **warn-by-default**. It prints `warning: unresolved link to `TileId::parse`` and still exits 0. So a pipeline of `fmt`, `clippy` and `test` publishes broken documentation without a single failure. ## Making rustdoc warnings fail | mechanism | where it lives | what it covers | |---|---|---| | `[lints.rustdoc]` with `broken_intra_doc_links = "deny"` | the manifest (or `[workspace.lints.rustdoc]`) | that lint, for every `cargo doc` by anyone | | `RUSTDOCFLAGS="-D warnings"` | CI environment | every rustdoc warning in that run | | `CARGO_BUILD_WARNINGS=deny` (Cargo 1.97+) | CI environment | lint warnings of local packages, in `cargo doc` as in `cargo build` or `cargo clippy` | All three made cargo 1.99.1 fail the test crate's `cargo doc --no-deps` with exit status 101. With the manifest form, rustdoc labels the error `requested on the command line with -D rustdoc::broken-intra-doc-links`, because Cargo turns the table into that flag. ## rustdoc lints worth knowing - `broken_intra_doc_links` (warn): a link that does not resolve. - `private_intra_doc_links` (warn): a public item linking to a private one, which readers of the public docs cannot follow. - `invalid_rust_codeblocks` (warn): a Rust code block that is empty or does not parse. - `bare_urls` (warn): a URL that is not written as a link. - `missing_crate_level_docs` (allow): no documentation at the crate root. `missing_docs`, by contrast, is a **rustc** lint: it belongs under `[lints.rust]` and fires in `cargo check`, not only in `cargo doc`. ## A documentation step for CI 1. Run `cargo doc --no-deps --workspace` (add `--all-features` if feature-gated items must be checked too). 2. Deny rustdoc warnings for that run, through `[lints.rustdoc]` in the manifest or `CARGO_BUILD_WARNINGS=deny` in the job. 3. Run `cargo clean --doc` first if the job publishes or archives `target/doc`, so stale pages from earlier runs are not shipped. 4. Keep it separate from `cargo test --doc`: one checks that examples compile and pass, the other that links and markup resolve, and neither does the other's job. ## docs.rs metadata When a crate is published, docs.rs builds its documentation on its own servers, and it cannot read your CI scripts. It reads `[package.metadata.docs.rs]` instead. Cargo ignores the whole `package.metadata` table and does not warn about unknown keys in it, which is what lets tools store settings there. Keys seen in widely used crates: - `all-features = true` or `features = [...]`, so feature-gated items appear in the docs; - `targets = [...]` to limit the platforms docs.rs builds; - `rustdoc-args = ["--cfg", "docsrs"]`, so the crate can enable documentation-only code with `#[cfg(docsrs)]`. Cargo already passes `--check-cfg 'cfg(docsrs,test)'` to rustc, so `#[cfg(docsrs)]` does not trigger `unexpected_cfgs`. To preview locally what docs.rs will render, run `RUSTDOCFLAGS="--cfg docsrs" cargo doc --no-deps --all-features`.
- Why does `target/doc` still contain dependency pages after a CI job switched to `cargo doc --no-deps`?Documentation generation is cumulative: Cargo keeps existing files in `target/doc` across runs, so pages from an earlier run without `--no-deps` stay. Run `cargo clean --doc` first when the output directory is what you publish or archive.
- How do you check locally that documentation gated behind features renders the way docs.rs will show it?Mirror the docs.rs settings: `RUSTDOCFLAGS="--cfg docsrs" cargo doc --no-deps --all-features`. That enables every Cargo feature and the `docsrs` cfg the manifest passes through `rustdoc-args`, so feature-gated items and `#[cfg(docsrs)]` code appear as they will on docs.rs.
- cargo build reports broken intra-doc links as warnings
- cargo test --doc fails when a doc link does not resolve
- cargo doc documents only your own crates by default
- docs.rs reads its build settings from the CI configuration
- missing_docs is a rustdoc lint that only runs in cargo doc
Assumes Cargo 1.99; build.warnings (CARGO_BUILD_WARNINGS), one of the ways to fail cargo doc on warnings, is stable since Cargo 1.97, and [lints.rustdoc] since Cargo 1.74.