docs: move examples into doc comments and cover them with doctests

[AbysmalBiscuit]

Put devkit.toml examples in the doc comments next to the types they describe, and make them doctests so an example that stops being valid fails the build instead of rotting.

Why here

The doc comment is already the upstream of the generated reference: devkit schema renders its 156 descriptions straight from the Rust doc comments on the config types. An example added there flows into the schema for free, with no second copy to keep in sync.

It is also the only place an example can be executed. CI already runs cargo test --workspace --doc as its own step. A TOML example in a devkit-config doc comment can parse through Config::parse inside the doctest, so a stale example is a red build rather than a reader's problem.

Today the examples live in docs/configuration.md, where nothing checks them and nothing generates them.

Scope

1. Move the worked devkit.toml examples from docs/configuration.md onto the config types in crates/devkit-config.
2. Wrap each in a doctest that parses it through Config::parse and asserts the shape it demonstrates.
3. Confirm the examples render usefully in devkit schema output, since the descriptions carry the doc comment verbatim.

Open questions

• Do the doctests parse examples only, or also assert rendered output for the templating ones? Asserting the render is stronger and costs a minijinja pass per doctest.
• Does an example belong on every type, or only where the shape is not obvious from the field list?

Related

#59 removes the reference prose that restates generated output. This issue supplies the replacement, so landing it first leaves less to relocate there.

🤖 Generated with Claude Code