find a way to run doc tests against code snippets

[clux]

as explored in #1 - we tried using mdbook as the nice rust-native markdown book webpage generator for its killer feature: being able to run doc tests.

unfortunately, the feature as it stands is extremely limited: rust-lang/mdBook#706 , and the book ui also leaves a lot to be desired.

therefore, this is an exploration issue (possibly for the far future) to find a way to do this externally.

some potentials:

• having a docs/SUMMARY.md + book.toml present in the repo just for doc tests (if they fix 706)
• create a local crate with doc-comment pull-ins / rust-skeptic that's tested via cargo test --doc on ci here

i explored the latter approach within kube-rs repo a few months ago and found it very painful (needed a lot of doc comments that cannot be hidden except through shell hackery - which did not work for the root README.md)

[clux]

LucaP has done this for materialize-mkdocs using an mkdocs plugin with a generator that inlines snippets: https://www.lpalmieri.com/posts/this-month-in-pavex-08/

It currently lives in https://github.com/LukeMathWalker/pavex/blob/db8fb67210e242d6ca81aafe14f66f1217f49085/doc_examples/tutorial_generator/src/main.rs

maybe something like this could be factored out of pavex and made general purpose?

mastodon thread