Bevy book code should be compiled against new releases #83
Milestone
Comments
|
In my experience, Zola is great when you stay in its scope, but not very pluggable for pre- or post-processing. I don't think it would be possible to use it with compiled code without doing quite a few external scripts. The best solution for checked code snippets is mdbook |
|
there you go: #143 😉 |
Closed
This was referenced Jan 8, 2022
2 tasks
bors bot
pushed a commit
that referenced
this issue
Mar 11, 2022
# Objective Migrates #203 Closes #83 # Solution - [x] Add code validation - [x] ~~Add code format checking~~ Removed to unblock the code validation changes # Problems During the implementation of the code validation and the format checking I encountered some problems which I would appreciate guidance or help with. ## Need to be addressed 1. ~~Zola doesn't highlight the code blocks using the rust syntax if you add more than just the language to the code block attributes. Example `rust` highlights the code correctly, `rust,no_run` doesn't. So currently the code highlighting is broken.~~ Zola is order dependent for attributes (as noted by @mockersf). So changing the attribute order from `rust,no_run` to `no_run,rust` works just fine. 1. Running `cargo fmt` doesn't format the doc examples. Adding the `rustfmt.toml` option `format_code_in_doc_comments = true` enables this, but requires nightly. In my tests it also only works if you add the code examples directly without using `#[doc = include_str!("_index.md")]`. So currently the format checking is not working. ## Nice to have 1. The `lib.rs` file of the `code-validation` crate has to be manually updated each time a new `_index.md` file is added or removed. It might be a good idea to dive deeper and see if we can implement a solution where this work is done automatically. For now this should be more than fine though. Co-authored-by: KDecay <KDecayMusic@protonmail.com>
|
Fixed by #281. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
There have been a number of cases where the Bevy book falls out of sync from the most recent release and stays that way for a while, confusing new users that come on board right after an exciting new release.
To that end, this code should be fully compiled with Bevy as a dependency, and then its examples checked against the release candidate before the release goes live. Copy-pasting the code into test scripts is tedious, so it would be nice if this occurred more automatically.
I know mdbook supports this smoothly (because I support in Understanding Bevy); I'm not sure that you can do the same in Zola. As an added bonus, swapping to mdbook (#47) lets end users run the example code directly if they clone this repo.
The text was updated successfully, but these errors were encountered: