Skip to content

[xtask] Add aggro subcommand for building aggregate docs#2481

Draft
jamesmunns wants to merge 9 commits intomasterfrom
james/xtask-aggro
Draft

[xtask] Add aggro subcommand for building aggregate docs#2481
jamesmunns wants to merge 9 commits intomasterfrom
james/xtask-aggro

Conversation

@jamesmunns
Copy link
Copy Markdown
Contributor

@jamesmunns jamesmunns commented Apr 17, 2026

I've currently plumbed a good "base coat" of the aggro subcommand (name bikeshedding welcome, it was funny on a Friday morning), which generally:

  • Takes a task config
  • Figures out all the tasks in that config
  • Splats all of the READMEs (that are present) into a single bundle, and renders them into a single HTML "report".

Currently, it looks like this:

Screenshot 2026-04-20 at 15-53-02 cosmo-b Aggregate Docs

aggro.html

From now, there are a couple of questions:

  1. I could use some feedback on "matters of taste":
  • What information WOULD be useful to document on a per-app, or a per-task basis?
  • I included some simple tables, but these should be considered a proof of concept.
  • How do we want to shape this? One big MD/HTML/PDF file? Something more multi-page organized like mdbook?
  1. I think we'll want to make a pass over our task docs:
  • Most tasks don't have any docs! But we can backfill this :)
  • We probably want to set out a bit of a "standard" of how drivers+tasks+apps are documented

I did try figuring out how to insert the task graph, sadly the launch-rs crate isn't as good at layouting as the dot bin is, and neither are great for making legible diagrams. We may want to break this up on a per-task basis just to reduce the number of entities per-graph.

Screenshot 2026-04-17 at 7 33 04 PM

@jamesmunns jamesmunns requested review from cbiffle and mkeeter April 17, 2026 18:55
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