ECS magic section for ECS chapter #293
Conversation
Book structure
Book structure
Enabled the anchor links in every `_index.md` file inside of the `content/learn/book` section. I ported the changes made in bevyengine#275 over to the `new_book` branch. Closes bevyengine#274 Closes bevyengine#275
# Objective Migrates bevyengine#203 Closes bevyengine#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 <[email protected]>
- Fixes bevyengine#207 # Status - [x] Split the PR - [x] Merge bevyengine#272 (do first to reduce dumb merge conflicts). - [x] Fix all mdlint violations - [x] Update CI to target `master` rather than `main` (or fix the branch name per bevyengine#140 ) - [x] Add local rules to ignore the same lints to improve contributor experience. I followed [these instructions](https://github.com/DavidAnson/vscode-markdownlint#configure); simply renaming the version in the .github folder didn't resolve the problem for me.
Quick follow-up to bevyengine#281.
I intend to close and split bevyengine#182 to improve both development and review workflows. This is a tiny PR to make reviewing that work less painful by reducing weird branch issues.
|
Tempted to say we should have a separate section for "engine internals" akin to the Rustonomicon that explains the structure of internals and the type system magic that is employed. It's not needed for most users in for practical purposes. We can still point people who are genuinely curious there, but it shouldn't be right there on the sidebar for an intro to the engine. |
Yep, this is one of my big questions about this section. It's clearly valuable (I've pointed half-a-dozen grateful users to it already), but it's not at all clear that it belongs as part of the ECS chapter, or even the Bevy book. |
|
As a newcomer, I got a similar sensation while reading the Commands section: #291 . Apart of the "engine internal", maybe some of the "commands" sub-sections can be moved to a "how to…"? |
|
Closing this out. It's way too hard to keep up-to-date and of questionable value to readers at this level. That said, expect a blog post on the topic from me in the future. |
Extracted from #182.
Status