Proof of concept for runnable doc tests in leptos book #135
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.
Trying out a workaround that will allow code snippets in the leptos book run as doctests.
mdbook
does not support this for leptos, because it does not invokerustdoc
with references to all the dependencies in the cargo project.The approach here is the one used by the Rust team for their books: extract the snippets into a source project, then
{{rustdoc_include
them from the code block in the.md
file.The proof of concept is limited to chap 9.2, Nested Routes (because that was the area I most need to learn right now). and only affects the first 5 snippets in the chapter. The snippets render basically the same, except there are hidden boilerplate source lines that can be revealed with the "eye" button so you can what makes the snippet compilable.
The snippet doctests have been converted to unit tests: run
cargo test
and observe that it now includes the source files containing the snippets. You could add assertions or other proof-of-life code to be verified in the test.Note too that there's a compile error in one of the snippets: I found a snippet that hadn't been updated for 0.7 yet, but couldn't figure out how to fix it.
The POC has glitches:
.md
file.So I'm submitting the POC now to see if the leptos team has any interest in this approach.