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

Test documentation code snippets during CI #230

Closed
lambda-fairy opened this issue Oct 11, 2020 · 2 comments · Fixed by #257
Closed

Test documentation code snippets during CI #230

lambda-fairy opened this issue Oct 11, 2020 · 2 comments · Fixed by #257
Assignees

Comments

@lambda-fairy
Copy link
Owner

lambda-fairy commented Oct 11, 2020

Much like what's done with mdbook test.

I think the most important part is the web framework integration page because that's an external integration point.

One complication is that the documentation build doesn't include the web framework support. And for good reason – the build with --all-features takes twice as long. So this test step will have to be stuck on the end of the "All features" build, which I guess is okay but kind of strange.

@lambda-fairy
Copy link
Owner Author

My current approach is to have a dummy crate that imports the book's contents using #[doc = include_str!("...")]. Then running cargo test on that crate will test all the code snippets in the book.

An alternative is to invoke rustdoc directly, with something like:

rustdoc --edition=2018 --test -L maud/target/debug docs/content/*.md

mdBook uses this approach. But this bypasses Cargo, which leads to two disadvantages:

  1. I have to arrange for all the dependencies to be built before running the test.
  2. The extern prelude is not populated automatically. This means I have to maintain the --extern flags by hand, or litter the examples with extern crate maud;.

@lambda-fairy
Copy link
Owner Author

Another alternative is to use rust-skeptic, but I think our hand-rolled approach is simple enough that it's not worth bringing in another dependency to do it.

lambda-fairy added a commit that referenced this issue Jan 15, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant