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 invoke rustdoc 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:
All the converted snippets currently live in one file, so when you unhide any snippet, it shows lots of irrelevant code.
Making the snippet source file unit testable means the file name must not start with a digit (because it's used as a module name...).
It implies a fairly big change in the doc workflow, getting pretty far from the elegance of doctests right in the .md file.
So I'm submitting the POC now to see if the leptos team has any interest in this approach.
Trying out a workaround that will allow code snippets in the leptos book run as doctests.
mdbookdoes not support this for leptos, because it does not invokerustdocwith 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_includethem from the code block in the.mdfile.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 testand 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:
.mdfile.So I'm submitting the POC now to see if the leptos team has any interest in this approach.