From ff940d6722cbb8b4bdcaa4dcb45725245c6d957f Mon Sep 17 00:00:00 2001 From: TrialDragon <31419708+TrialDragon@users.noreply.github.com> Date: Tue, 6 Feb 2024 06:56:02 -0800 Subject: [PATCH] Generate Zola Rust code block hidden lines annotations in the book (#922) --- CONTRIBUTING.md | 3 +- .../book/ecs/entities-components/_index.md | 18 +++----- .../getting-started/modular-plugins/_index.md | 2 +- .../getting-started/apps/_index.md | 5 +-- .../quick-start/getting-started/ecs/_index.md | 41 +++++++------------ .../getting-started/plugins/_index.md | 12 ++---- .../getting-started/resources/_index.md | 9 ++-- .../quick-start/plugin-development/_index.md | 2 +- .../write_rustdoc_hide_lines.sh | 1 + 9 files changed, 34 insertions(+), 59 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d4b3b56c52..61cb49eb55 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -173,7 +173,8 @@ These may be appropriate to link in "next steps" however at the end of the examp 9. If additional code block attributes like `no_run` or `hide-lines=x-y` need to be specified, you should always order these so that the language is the last attribute. If we would specify `rust,no_run` the syntax highlighting wouldn't work, but changing it to `no_run,rust` makes it work. 10. To validate if local code changes are compiling you can `cd` into the `code-validation` folder and test your code using `cargo test`. 11. To make sure your markdown files are formatted correctly run `markdownlint -f -c .github/linters/.markdown-lint.yml .` in the root directory of your local Bevy website repository. -12. To reference Rust API docs you can use markdown's reference-style links like so: +12. To hide lines of code in Zola Rust code blocks of the book you should: a. Mark each line you wish to hide with a `#` with an empty space afterwards like `# //...line_of_code_here...` although you were hiding lines in rustdoc. b. Run the [utility tool](write-rustdoc-hide-lines) in `/write_rustdoc-hide-lines/` named `write_rustdoc_hide_lines.sh`. +13. To reference Rust API docs you can use markdown's reference-style links like so: [`HashMap`] ```md diff --git a/content/learn/book/ecs/entities-components/_index.md b/content/learn/book/ecs/entities-components/_index.md index 93b5fd133f..0e713bbe6f 100644 --- a/content/learn/book/ecs/entities-components/_index.md +++ b/content/learn/book/ecs/entities-components/_index.md @@ -27,9 +27,8 @@ Once entities exist, they can likewise be despawned, deleting all of the data st Spawning and despawning entities can have far-reaching effects, and so cannot be done immediately (unless you are using an [exclusive system](../exclusive-world-access)). As a result, we must use [`Commands`], which queue up work to do later. -```rust +```rust,hide_lines=1 # use bevy::ecs::system::Commands; - // The `Commands` system parameter allows us to generate commands // which operate on the `World` once all of the current systems have finished running fn spawning_system(mut commands: Commands){ @@ -58,9 +57,8 @@ You will almost always want to use the `#[derive(Component)]` [macro](https://do With the theory out of the way, let's define some components! -```rust +```rust,hide_lines=1 # use bevy::ecs::component::Component; - // This is a "unit struct", which holds no data of its own. #[derive(Component)] struct Combatant; @@ -91,7 +89,7 @@ enum Allegiance { Now that we have some components defined, let's try adding them to our entities using [`Commands`]. -```rust +```rust,hide_lines=1-20 # use bevy::ecs::prelude::*; # # #[derive(Component)] @@ -112,7 +110,6 @@ Now that we have some components defined, let's try adding them to our entities # Friendly, # Hostile # } - fn spawn_combatants_system(mut commands: Commands) { commands.spawn(( // This inserts a data-less `Combatant` component into the entity we're spawning @@ -150,12 +147,11 @@ fn spawn_combatants_system(mut commands: Commands) { Once an entity is spawned, you can use [`Commands`] to add and remove components from them dynamically. -```rust +```rust,hide_lines=1-4 # use bevy::ecs::prelude::*; # # #[derive(Component)] # struct Combatant; - #[derive(Component)] struct InCombat; @@ -189,7 +185,7 @@ These are defined by deriving the [`Bundle`] trait for a struct; turning each of Let's try rewriting that code from above. -```rust +```rust,hide_lines=1-20 # use bevy::prelude::*; # # #[derive(Component)] @@ -210,7 +206,6 @@ Let's try rewriting that code from above. # Friendly, # Hostile # } - #[derive(Bundle)] struct CombatantBundle { combatant: Combatant, @@ -279,7 +274,7 @@ Including duplicate components in your bundles in this way will cause a panic. With those caveats out of the way, let's take a look at the syntax by converting the bundle above to a nested one by creating a bundle of components that deal with related functionality. -```rust +```rust,hide_lines=1-19 # use bevy::prelude::*; # # #[derive(Component)] @@ -299,7 +294,6 @@ With those caveats out of the way, let's take a look at the syntax by converting # Friendly, # Hostile # } - #[derive(Bundle)] struct AttackableBundle{ life: Life, diff --git a/content/learn/book/getting-started/modular-plugins/_index.md b/content/learn/book/getting-started/modular-plugins/_index.md index ba3cb9dc04..8f27e9c175 100644 --- a/content/learn/book/getting-started/modular-plugins/_index.md +++ b/content/learn/book/getting-started/modular-plugins/_index.md @@ -4,4 +4,4 @@ weight = 4 template = "docs-section.html" [extra] status = 'hidden' -+++ \ No newline at end of file ++++ diff --git a/content/learn/quick-start/getting-started/apps/_index.md b/content/learn/quick-start/getting-started/apps/_index.md index 7d2ce5b99a..64f9db3e3a 100644 --- a/content/learn/quick-start/getting-started/apps/_index.md +++ b/content/learn/quick-start/getting-started/apps/_index.md @@ -10,9 +10,8 @@ aliases = ["learn/book/getting-started/apps"] Bevy programs are referred to as [`App`]s. The simplest Bevy app looks like this: -```rs -use bevy::prelude::*; - +```rs,hide_lines=1 +# use bevy::prelude::*; fn main() { App::new().run(); } diff --git a/content/learn/quick-start/getting-started/ecs/_index.md b/content/learn/quick-start/getting-started/ecs/_index.md index 330c30fbff..0d785aff43 100644 --- a/content/learn/quick-start/getting-started/ecs/_index.md +++ b/content/learn/quick-start/getting-started/ecs/_index.md @@ -20,18 +20,16 @@ Bevy ECS is Bevy's implementation of the ECS pattern. Unlike other Rust ECS impl * **Components**: Rust structs that implement the [`Component`] trait - ```rs + ```rs,hide_lines=1 # use bevy::prelude::*; - #[derive(Component)] struct Position { x: f32, y: f32 } ``` * **Systems**: normal Rust functions - ```rs + ```rs,hide_lines=1 # use bevy::prelude::*; - fn print_position_system(query: Query<&Position>) { for position in &query { println!("position: {} {}", position.x, position.y); @@ -41,9 +39,8 @@ Bevy ECS is Bevy's implementation of the ECS pattern. Unlike other Rust ECS impl * **Entities**: a simple type containing a unique integer - ```rs + ```rs,hide_lines=1 # use bevy::prelude::*; - struct Entity(u64); ``` @@ -55,9 +52,8 @@ Now let's see how this works in practice! Paste the following function into your `main.rs` file: -```rs +```rs,hide_lines=1 # use bevy::prelude::*; - fn hello_world() { println!("hello world!"); } @@ -65,9 +61,8 @@ fn hello_world() { This will be our first system. The only remaining step is to add it to our [`App`]! -```rs -use bevy::prelude::*; - +```rs,hide_lines=1 +# use bevy::prelude::*; fn main() { App::new() .add_systems(Update, hello_world) @@ -90,27 +85,24 @@ Greeting the whole world is great, but what if we want to greet specific people? Add this struct to your `main.rs` file: -```rs +```rs,hide_lines=1 # use bevy::prelude::*; - #[derive(Component)] struct Person; ``` But what if we want our people to have a name? In a more traditional design, we might just tack on a `name: String` field to `Person`. But other entities might have names too! For example, dogs should probably also have a name. It often makes sense to break datatypes up in to small pieces to encourage code reuse. So let's make `Name` its own component: -```rs +```rs,hide_lines=1 # use bevy::prelude::*; - #[derive(Component)] struct Name(String); ``` We can then add people to our [`World`] using a "startup system". Startup systems are just like normal systems, but they run exactly once, before all other systems, right when our app starts. Let's use [`Commands`] to spawn some entities into our [`World`]\: -```rs +```rs,hide_lines=1 # use bevy::prelude::*; - fn add_people(mut commands: Commands) { commands.spawn((Person, Name("Elaina Proctor".to_string()))); commands.spawn((Person, Name("Renzo Hume".to_string()))); @@ -120,9 +112,8 @@ fn add_people(mut commands: Commands) { Now register the startup system like this: -```rs +```rs,hide_lines=1 # use bevy::prelude::*; - fn main() { App::new() .add_systems(Startup, add_people) @@ -138,9 +129,8 @@ fn main() { We could run this now and the `add_people` system would run first, followed by `hello_world`. But our new people don't have anything to do yet! Let's make a system that properly greets the new citizens of our [`World`]: -```rs +```rs,hide_lines=1 # use bevy::prelude::*; - fn greet_people(query: Query<&Name, With>) { for name in &query { println!("hello {}!", name.0); @@ -155,9 +145,8 @@ You can interpret the [`Query`] above as: "iterate over every `Name` component f Now we just register the system in our `App`. Note that you can pass more than one system into an `add_systems` call by using a tuple! [`Query`]: -```rs +```rs,hide_lines=1 # use bevy::prelude::*; - fn main() { App::new() .add_systems(Startup, add_people) @@ -183,9 +172,8 @@ Marvelous! If we want to change the names of some people (perhaps they got married!), for example, we can do this using a mutable query: -```rs +```rs,hide_lines=1 # use bevy::prelude::*; - fn update_people(mut query: Query<&mut Name, With>) { for mut name in &mut query { if name.0 == "Elaina Proctor" { @@ -200,9 +188,8 @@ We need to make `query` mutable, and use a mutable reference (`&mut`) to the com Don’t forget to add the system to the [`Update`] schedule: -```rs +```rs,hide_lines=1 # use bevy::prelude::*; - fn main() { App::new() .add_systems(Startup, add_people) diff --git a/content/learn/quick-start/getting-started/plugins/_index.md b/content/learn/quick-start/getting-started/plugins/_index.md index 65556ac01c..8482f3c755 100644 --- a/content/learn/quick-start/getting-started/plugins/_index.md +++ b/content/learn/quick-start/getting-started/plugins/_index.md @@ -26,9 +26,8 @@ However, most developers don't need a custom experience and just want the "full Let's make our app more interesting by adding Bevy's [`DefaultPlugins`] which are a [`PluginGroup`] containing core engine features. (For those needing minimal features, [`MinimalPlugins`] exists). `add_plugins(DefaultPlugins)` adds the features most people expect from an engine, such as a 2D / 3D renderer, asset loading, a UI system, windows, and input. -```rs +```rs,hide_lines=1 # use bevy::prelude::*; - fn main() { App::new() .add_plugins(DefaultPlugins) @@ -49,9 +48,8 @@ You should hopefully notice two things: For better organization, let's move all of our "hello" logic to a plugin. To create a plugin we just need to implement the [`Plugin`] interface. Add the following code to your `main.rs` file: -```rs +```rs,hide_lines=1 # use bevy::prelude::*; - pub struct HelloPlugin; impl Plugin for HelloPlugin { @@ -63,9 +61,8 @@ impl Plugin for HelloPlugin { Then register the plugin in your App like this: -```rs +```rs,hide_lines=1 # use bevy::prelude::*; - fn main() { App::new() .add_plugins((DefaultPlugins, HelloPlugin)) @@ -77,9 +74,8 @@ fn main() { Note `add_plugins` can add any number of plugins (or plugin groups like `DefaultPlugins`) by passing in a tuple of them. Now all that's left is to move our systems into `HelloPlugin`, which is just a matter of cut and paste. The `app` variable in our plugin's `build()` function is the same builder type we use in our `main()` function: -```rs +```rs,hide_lines=1 # use bevy::prelude::*; - impl Plugin for HelloPlugin { fn build(&self, app: &mut App) { app.add_systems(Startup, add_people) diff --git a/content/learn/quick-start/getting-started/resources/_index.md b/content/learn/quick-start/getting-started/resources/_index.md index e72e77cf15..b59e85cc52 100644 --- a/content/learn/quick-start/getting-started/resources/_index.md +++ b/content/learn/quick-start/getting-started/resources/_index.md @@ -28,9 +28,8 @@ For simplicity, remove the `hello_world` system from your App. This way we only Resources are accessed in much the same way that we access components. You can access the [`Time`] resource in your system like this: -```rs +```rs,hide_lines=1 # use bevy::prelude::*; - fn greet_people(time: Res