docs: generate crate READMEs from lib.rs with cargo-rdme, checked in CI#93
Merged
Merged
Conversation
The execution_graph README Quick Start had dropped `?` on `add_node`/`set_input_value` (both return `Result`), so the `fn main()` example failed to compile with two E0308s — a reader's first copy-paste would not build. Fix the root cause: make each crate's src/lib.rs doc comment the single source of truth and generate the README body from it via cargo-rdme (between `<!-- cargo-rdme start/end -->` markers), matching the convention used in other org repos (e.g. understory). A new `cargo rdme` CI job runs `--check` per crate so a README can never drift from its docs again. The richer README content (Model, Core Pieces, etc.) was migrated into the doc comments so nothing is lost and the docs.rs pages now carry the full guide; the Quick Start examples are compiled and run by the existing `cargo test --doc` step.
waywardmonkeys
approved these changes
Jun 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
The
execution_graphREADME Quick Start didn't compile: thefn main()example had dropped?onadd_nodeandset_input_value(both returnResult), producing twoE0308s. A reader's first copy-paste from the docs would fail to build, while thelib.rsdoctest stayed correct because only it was exercised by CI.Rather than just patch the README, this fixes the root cause — the README was a hand-transcribed copy of the doctest, free to drift.
Approach
Adopt
cargo-rdme, matching the convention used in other org repos (e.g.understory):src/lib.rsdoc comments are the single source of truth. Each README body is generated from them, between<!-- cargo-rdme start/end -->markers.cargo rdmeCI job runscargo rdme --workspace-project=<crate> --heading-base-level=0 --checkforexecution_tapeandexecution_graph, so a README can never drift from its docs again.cargo test --docstep (execution_tape's example was upgraded fromno_runto executed).Verification
cargo rdme --checkpasses for both cratescargo test --doc --workspacepassescargo fmt --check,cargo clippy -- -D warnings, andcargo docwith--cfg docsrs -D warningsall cleanUpdating a README
Edit the doc comment in
src/lib.rsand run the same command without--check; a reminder comment is in eachlib.rsand README.