policy(rust): drop the cargo doc / rustdoc CI lane — agents read source, not rendered docs

[zackees]

Proposal

Remove the cargo doc / rustdoc lane from the fleet PR gate. Code in the fleet is increasingly read by AI agents that work from source, not by people browsing rendered rustdoc. A PR job that builds HTML docs (typically RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps) spends runner minutes on an artifact that nobody consumes. Agents read doc comments straight from the .rs files.

Measured cost: FastLED/fbuild docs.yml

The job (.github/workflows/docs.yml, "Documentation") runs on pull_request and on push to main. It uses one ubuntu-latest job with RUSTDOCFLAGS: "-D warnings", setup-soldr with build/target cache, and then soldr cargo doc --workspace --no-deps. The output is not uploaded or published anywhere.

Eight most recent successful PR runs (2026-09-29):

Run ID	Job wall time	Build docs step
36530429770	5m43s	5m33s
36528338039	5m02s	4m34s
36527717856	5m49s	5m28s
36527641741	6m07s	5m48s
36525554151	4m16s	4m00s
36525258721	4m45s	4m23s
36522564568	4m53s	4m39s
36519171733	5m50s	5m41s

• The median job time is about 5m22s, and the Build docs step's median is about 5m04s. The range is 4m16s to 6m07s.
• On ci: compile fbuild once, path-selected board dispatch (badges stay current), main-only cache saves FastLED/fbuild#1574, the "Documentation" check took 4m45s.
• The cost is about 5 to 6 runner-minutes per PR push, plus one more run per merge to main. The build cache is already warm, so this is steady-state cost, not a cold-start cost.

What stays

• Doc comments. They are still valuable, because agents read them in source. This issue does not propose dropping them.
• Doctests. They are real tests. A repo that relies on them keeps running them with cargo test --doc, or through the normal cargo test run, which includes doctests for library crates. That path does not build HTML. This issue does not propose dropping doctests.
• Publishing repos. A repo that actually publishes rendered docs (docs.rs, GitHub Pages) can keep a doc build, ideally on the publish/release path rather than on every PR.

Accepted trade-off

A rustdoc build with -D warnings catches broken intra-doc links (rustdoc::broken_intra_doc_links) and malformed doc markup. Without the lane, those can land. This is the accepted trade-off: a broken [Foo] link in source still names the right symbol for a reader grepping the code, and it only matters to a rendered-HTML consumer, which this policy assumes does not exist unless the repo declares one.

Current policy text

A search of docs/policy-rust.md, docs/policy-general.md, docs/ci-toml.md and ci_lint/ found no rule that requires a doc/rustdoc lane. The only related mentions are:

• docs/ci-toml.md L649, TOOL-002: "A dependency-resolving cargo subcommand (build/test/check/clippy/doc/run/nextest) without --locked." This lists doc only so that a doc job, if one exists, must pass --locked.
• docs/policy-rust.md RUST-006 and docs/policy-general.md CACHE-007 mention "doctest product" as a class of content that must not be cached. Both are unaffected.

So the lane exists in repos like fbuild by convention, not because policy requires it. The change is therefore an addition, not an edit:

1. Add a Rust rule to docs/policy-rust.md, for example RUST-0xx: "A PR-gate job runs cargo doc / rustdoc (or sets RUSTDOCFLAGS) and the repository does not declare that it publishes rendered docs." Status: candidate.
2. Once the rule lands, optionally drop doc from the TOOL-002 subcommand list, or keep it for the allow-listed publishing repos.

Proposed ci_lint check (candidate)

A static precheck that flags any job reachable from the PR entrypoint (pull_request trigger or ci.yml workflow_call graph) whose steps run cargo doc / soldr cargo doc / rustdoc, or that sets RUSTDOCFLAGS in job or step env. It passes when ci.toml carries an explicit allow entry declaring where the docs are published, for example:

[rust.docs]
publishes = "docs.rs"   # or "pages"; required reason for keeping a doc build

cargo test --doc must not trigger the check.

Related

• policy(rust): never run cargo check before cargo clippy on the same target set (clippy is a superset; ~45% of the lint lane wasted) #115: a redundant cargo check before clippy. It is the same pattern: a second pass that produces nothing anyone consumes.

[zackees]

Correction to the proposed opt-in: derive it from Cargo.toml, not a new ci.toml key. Cargo already records whether a crate's docs are published, so a second declaration would only drift:

• publish = false (in [package], or inherited via publish.workspace = true) means the crate never reaches crates.io, so docs.rs never builds it. No rendered docs exist, and the doc lane has no consumer.
• A crate that is published (publish absent or listing registries) gets built by docs.rs automatically, so a PR-gate rustdoc check is justified: it catches a docs.rs build failure before release.
• [package.metadata.docs.rs] (features, targets, rustdoc-args for docs.rs) is an explicit signal that docs are published and configured, which also justifies the lane.

Proposed rule, revised: flag a PR-gate cargo doc / RUSTDOCFLAGS job unless at least one workspace member is publishable or declares [package.metadata.docs.rs]. The lane should then document only those members (-p …), not --workspace. A separately hosted doc site (Pages) is the one case Cargo.toml can't express, and it would need a scoped [allow] entry.

Applied in FastLED/fbuild#1574: every crate there is publish = false with no docs.rs metadata, so the Documentation job (median ~5m22s per PR push) was removed. Doctests still run under cargo test --workspace.

[zackees]

Fleet inventory (2026-09-30): which repos still run a Rust doc check. The owner's instruction is to file this as policy and not to do the removals, so this is evidence only; no repo has been changed.

Scanned every non-archived, non-fork repo in zackees, FastLED and TechWatchProject that contains a Cargo.toml (24 repos): workflows, composite actions, ci/ and script files, then re-verified by git grep on the default branch of soldr, clud, kernal-api, running-process, zccache, reld, bosn and fbuild.

Still running a doc check (remove candidates):

Repo	Where	What
zackees/zccache	.github/workflows/ci.yml:353 (PR check "Documentation") and ci/lint.py:337-339	soldr cargo doc --workspace --no-deps, RUSTDOCFLAGS=-D warnings; also part of local lint, so local lint pays for it too
zackees/running-process	.github/workflows/ci-preflight.yml:298-299	cargo doc -p running-process --features daemon --no-deps, RUSTDOCFLAGS=-Dwarnings

Already gone: FastLED/fbuild (the docs.yml "Documentation" job measured in this issue no longer exists; removed in the 2026-09-29 "compile fbuild once, path-selected board dispatch" restructure).

Not doc checks (must not trigger the rule):

• zackees/clud: ci/xbuild.py::cmd_doctest runs cargo test --workspace --doc (~7 s in the build job). That is a doctest, a real test, explicitly kept by this issue.
• zackees/reld: sanitizers.yml sets RUSTDOCFLAGS=-Zsanitizer=address (sanitizes doctests); this is a RUSTDOCFLAGS hit the proposed static check must not flag as a docs lane (the rule should key on cargo doc/rustdoc invocations, or allow -Zsanitizer= flags).
• zackees/soldr: ci/smoke_published_dylint.py only scrubs RUSTDOCFLAGS from the environment (SCRUB_EXACT); soldr's tests check cargo doc front-door routing but CI does not run cargo doc.

No doc check found: bosn, mimalloc-pprof, ai-tools, kernal-api, template-python-rust-cmd, python-rust-build-chain, setup-soldr, soldr-toolchain, FastLED/cli, FastLED/fbuild-ide, TechWatchProject/extension2, datalake-core, textract.kumquat.link.

Consequences for the proposed check in this issue: (1) RUSTDOCFLAGS alone is not a reliable signal (reld, soldr), so key on a cargo doc / soldr cargo doc / rustdoc invocation and treat RUSTDOCFLAGS as corroboration only; (2) zccache's invocation lives in a script (ci/lint.py) as well as in a workflow, so the check must follow one level into ci/*.py as RUST-002/GEN-004 already do; (3) neither remaining repo is a publishing repo by the Cargo.toml rule in the correction above, but that is unverified here (I did not read their publish/[package.metadata.docs.rs] settings), so the removal PRs should check it first.

Limits: file cap of 160 per repo in the first pass (verified again by direct grep for the big repos); no search of non-Rust-doc CI (Pages publishing, mdBook) since those are not Rust doc checks.