Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proof of concept for runnable doc tests in leptos book #135

Open
wants to merge 4 commits into
base: 0.7
Choose a base branch
from

Conversation

bobhy
Copy link

@bobhy bobhy commented Nov 21, 2024

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.

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.

1 participant