Skip to content

fix(cli): keep the binary's pages out of the library's directory - #16

Merged
adammharris merged 1 commit into
mainfrom
agent/backlog-fix-cargo-doc-writes-the-cli-over-the-library
Nov 3, 2026
Merged

adammharris merged 1 commit into
mainfrom
agent/backlog-fix-cargo-doc-writes-the-cli-over-the-library

Conversation

@adammharris

Copy link
Copy Markdown
Member

What changed

  • plates-cli/Cargo.toml: the plates [[bin]] gets doc = false, so cargo doc --workspace writes only the library into target/doc/plates/.
  • .config/ship.figl: the Docs job pipes cargo doc through awk and fails on any output filename collision. RUSTDOCFLAGS='-D warnings' catches rustdoc's warnings but not Cargo's, so until now a collision passed.
  • The task is marked status: done with a status note, in place, as plates closes tasks.

Why

The binary and the library are both named plates, so both documented into one directory (rust-lang/cargo#6313), and target/doc/plates/index.html was the binary's, listing none of the library's modules. Of the task's candidates this takes the first (doc = false) and the third (a guard in the job), the same as historica#19. The second, moving the CLI's modules into a library target with its own doc directory, is still open if the binary's private modules should be documented locally.

Closes the task "cargo doc writes the CLI's pages over the library's" (docs/tasks/cargo-doc-writes-the-cli-over-the-library.md).

How it was verified

  • Guard added first, manifest unchanged, from an empty target/doc: ship ci docs fails on the collision warning.
  • After doc = false: ship ci docs passes with no collision, and target/doc/plates/ holds the library's modules (collect, digest, error, links, mount, plan, source, spec, term, theme) and no fn.main.html.
  • Full ship ci (all 7 jobs: fmt, clippy, test, docs, wasm, alone, msrv) passes.
  • prov check: no findings.

The `plates` binary in plates-cli and the `plates` library both documented
into `target/doc/plates/` (rust-lang/cargo#6313), so `cargo doc --workspace`
left the binary's index where the library's belonged. The `[[bin]]` now says
`doc = false`, and the Docs job fails on Cargo's `output filename collision`,
which `RUSTDOCFLAGS='-D warnings'` does not reach.

Closes docs/tasks/cargo-doc-writes-the-cli-over-the-library.md.
@adammharris
adammharris merged commit 134b3b0 into main Nov 3, 2026
8 checks passed
@adammharris
adammharris deleted the agent/backlog-fix-cargo-doc-writes-the-cli-over-the-library branch November 3, 2026 04:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant