Explore Validating Book Examples - #2566
Conversation
| @@ -0,0 +1,56 @@ | |||
| #![expect(dead_code)] | |||
There was a problem hiding this comment.
One thing to be aware of is that these kind of flags are needed for dead/unused code in these files. Definitely easy to overlook and get caught up when trying to run the validation script.
There was a problem hiding this comment.
i feel like extracting code examples into a separate file would make the markdown source & diff a lot harder to read
There was a problem hiding this comment.
plus examples sometimes show multiple ways of doing things, or ways that explicitly don't work/compile, which would cause problems with this approach
There was a problem hiding this comment.
Interesting, what makes you think that it would make the source/diff harder to read?
I think those cases you mention would still be feasible as long as the right flags are set. Not 100% sure on that, but I think I remember reading that there are flags for errors and code that won't compile. Multiple ways of doing things can also work I think, but it requires some adjustments to the way the code is structured in the standalone file.
Part of this is figuring out the areas where this approach doesn't work, so I do appreciate you bringing these up. There's nothing that says we absolutely need to convert every code block (even though I know I said it above) to this approach. It might even be a better idea to do some kind of hybrid approach, but then we need to figure out what works best for each method.
There was a problem hiding this comment.
Interesting, what makes you think that it would make the source/diff harder to read?
just the fact that they're now separated and the code block is not in-context with the words in the book
this also means they have to be kept in sync. if i change the words in the book, i have to go out of my way and look at another file to remember to change the code there to match what the book now says
There was a problem hiding this comment.
but I think I remember reading that there are flags for errors and code that won't compile
i think there are, but the problem is that it's either the entire file compiles or it doesn't. you can't say (at least not easily) that 'this portion of the file should fail to compile'
There was a problem hiding this comment.
this also means they have to be kept in sync.
Yeah that's fair. Personally, I don't think that it's too much extra work, considering people should really be building the website locally to review any bigger changes they make. CI would also possibly force people to remember to edit the code since the code is an example that the CI tests. It will always have to be working code that compiles against the latest version of Bevy. I think it'd also be worth it to include a sh file that runs all of the existing sh scripts. There's already one that validates the examples, so people wouldn't have to depend entirely on CI.
either the entire file compiles or it doesn't.
Valid, so this would probably be a good example of code that stays in code blocks rather than moved to an example file. If we know an example isn't going to compile, but we want to still showcase it for some reason, then it can stay in the markdown file.
3 participants
After rediscovering that we do in fact have an example validation tool in the repo, I've updated it's values and ported over a book page to see how it works out. If it works out, converting all example code blocks in the book would be a great step to ensuring that the book examples are both up to date and use the correct syntax. We should also update the Contributor's Guide to reflect this step in more detail, as it can be very easily overlooked as it currently is.