Skip to content

[xtask] Add support for xtask doc commands#2479

Open
jamesmunns wants to merge 1 commit intomasterfrom
james/xtask-docs
Open

[xtask] Add support for xtask doc commands#2479
jamesmunns wants to merge 1 commit intomasterfrom
james/xtask-docs

Conversation

@jamesmunns
Copy link
Copy Markdown
Contributor

This PR factors out a passthrough helper, and uses it for doc and clippy invocations.

Closes #2422

This somewhat punts on the flexibility items that @hawkw raised in #2422, as supporting both "before the --" and "after the --" args, in addition to the variable-length task list, was trickier than I wanted to get involved with in clap. That being said: it's not a feature anyone has needed yet, so I feel comfortable leaving that part as a todo.

@jamesmunns jamesmunns requested review from hawkw and mkeeter April 16, 2026 13:26
@jamesmunns
Copy link
Copy Markdown
Contributor Author

jamesmunns commented Apr 16, 2026

Ah, I did just notice one limitation of my approach:

Like xtask clippy, it is bound to task invocations, not package limitations. This may not actually fulfull the original request by @hawkw.

For example, this does work:

cargo xtask doc app/cosmo/rev-b.toml packrat -- --open

But this does not work:

cargo xtask doc app/cosmo/rev-b.toml ereports -- --open

edit: This does work, but requires some knowledge of which crate is used in which app+task:

cargo xtask doc app/grapefruit/rev-b.toml ereportulator -- -p ereports --open

@mkeeter
Copy link
Copy Markdown
Collaborator

mkeeter commented Apr 16, 2026

(I haven't read the implementation yet, but here's some thoughts on CLI stuff)

On one hand, it only makes sense to document packages in the context of a specific (manifest, task) tuple – tasks may enable / disable features in downstream crates which change docs.

On the other hand, it would be nice if this Just Worked™ in a sensible way. We do something similar in cargo xtask lsp by hard-coding a (increasingly out-of-date) set of manifests to check, then finding the first task in one of those manifests which uses the crate containing a source file.

I can think of a few ways to organize this at the CLI level:

  • cargo xtask doc app/cosmo/rev-b.toml [--task task] [target], where target is treated as either a crate or a task depending on whether --task is present (and if --task is present but target is absent, we target the task)
  • cargo xtask doc app/cosmo/rev-b.toml [--task task] [--crate crate], where we either document the task or the crate. This could also use the "find the first task which enables that package" strategy if --task is missing

I lean slightly towards the former, because it matches our existing CLI (e.g. cargo xtask build and the current cargo xtask clippy), but could be persuaded otherwise.

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.

an xtask for building RustDoc for Hubris crates would be nice

2 participants