Skip to content

docs: generate crate READMEs from lib.rs with cargo-rdme, checked in CI#93

Merged
no-materials merged 1 commit into
forest-rs:mainfrom
no-materials:docs/cargo-rdme-readmes
Jun 4, 2026
Merged

docs: generate crate READMEs from lib.rs with cargo-rdme, checked in CI#93
no-materials merged 1 commit into
forest-rs:mainfrom
no-materials:docs/cargo-rdme-readmes

Conversation

@no-materials
Copy link
Copy Markdown
Contributor

What & why

The execution_graph README Quick Start didn't compile: the fn main() example had dropped ? on add_node and set_input_value (both return Result), producing two E0308s. A reader's first copy-paste from the docs would fail to build, while the lib.rs doctest 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.rs doc comments are the single source of truth. Each README body is generated from them, between <!-- cargo-rdme start/end --> markers.
  • New cargo rdme CI job runs cargo rdme --workspace-project=<crate> --heading-base-level=0 --check for execution_tape and execution_graph, so a README can never drift from its docs again.
  • The richer README content (Model, Execution behavior, Core Pieces, Design Docs, …) 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 (execution_tape's example was upgraded from no_run to executed).

Verification

  • cargo rdme --check passes for both crates
  • cargo test --doc --workspace passes
  • cargo fmt --check, cargo clippy -- -D warnings, and cargo doc with --cfg docsrs -D warnings all clean

Updating a README

Edit the doc comment in src/lib.rs and run the same command without --check; a reminder comment is in each lib.rs and README.

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.
@no-materials no-materials merged commit 7ccb5f0 into forest-rs:main Jun 4, 2026
16 checks passed
@no-materials no-materials deleted the docs/cargo-rdme-readmes branch June 4, 2026 14:43
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.

2 participants