From e6498ad7bb09b6f5fc481c9a57abbab89e5a4859 Mon Sep 17 00:00:00 2001 From: Trevor Lovell Date: Sat, 11 Nov 2023 13:16:22 -0700 Subject: [PATCH 1/8] docs: add mdbook-keeper preprocessor --- book/book.toml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/book/book.toml b/book/book.toml index f7d58a6d..64c1ed18 100644 --- a/book/book.toml +++ b/book/book.toml @@ -5,3 +5,8 @@ multilingual = false src = "src" title = "bevy_ecs_ldtk Book" +[preprocessor.keeper] +command = "mdbook-keeper" +after = ["links"] +manifest_dir = "." +externs = ["bevy", "bevy_ecs_ldtk"] From a19c022c6ef3f6791b83934acfcdfd783d200bdd Mon Sep 17 00:00:00 2001 From: Trevor Lovell Date: Sat, 11 Nov 2023 13:16:53 -0700 Subject: [PATCH 2/8] docs: add basic getting-started page for testing mdbook-keeper --- book/src/SUMMARY.md | 2 +- book/src/getting-started.md | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) create mode 100644 book/src/getting-started.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 256b9ef6..eb9f12c6 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -2,7 +2,7 @@ [Introduction](README.md) # Tutorials -- [Getting Started]() +- [Getting Started](getting-started.md) - [Sokoban]() - [Platformer]() # Explanation diff --git a/book/src/getting-started.md b/book/src/getting-started.md new file mode 100644 index 00000000..01cfd82a --- /dev/null +++ b/book/src/getting-started.md @@ -0,0 +1,3 @@ +```rust,no_run +{{ #include ../../examples/basic.rs }} +``` From d38d73471d124812eb256aeead5e2dfb98b7a9ae Mon Sep 17 00:00:00 2001 From: Trevor Lovell Date: Sat, 11 Nov 2023 14:06:49 -0700 Subject: [PATCH 3/8] ci: add ci for building/testing book --- .github/workflows/lint.yml | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index df9d37ab..57dd7168 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -103,3 +103,31 @@ jobs: components: rustfmt - name: Run cargo fmt run: cargo fmt --all -- --check + + # Run mdbook build (tests all code snippets) + build-test-book: + name: Build and test book + runs-on: ubuntu-latest + steps: + - name: Checkout sources + uses: actions/checkout@v3 + - name: Cache + uses: actions/cache@v3 + with: + path: | + ~/.cargo/bin/ + ~/.cargo/registry/index/ + ~/.cargo/registry/cache/ + ~/.cargo/git/db/ + target/ + key: ${{ runner.os }}-mdbook-build-${{ hashFiles('**/Cargo.toml') }} + - name: Install stable toolchain + uses: dtolnay/rust-toolchain@stable + - name: Install mdbook + uses: peaceiris/actions-mdbook@v1 + with: + mdbook-version: '0.4.35' + - name: Install mdbook-keeper + run: cargo install mdbook-keeper --git https://github.com/tfpk/mddbook-keeper/ --rev 12f116d0840c69a6786dba3865768af3fde634f3 + - name: Run mdbook build (tests all code snippets) + run: CARGO_MANIFEST_DIR=. mdbook build book From f7d4b39e5c2495498bdd5b15fd88fe734f6403cf Mon Sep 17 00:00:00 2001 From: Trevor Lovell Date: Sat, 11 Nov 2023 15:01:07 -0700 Subject: [PATCH 4/8] ci: fix mdbook-keeper git link --- .github/workflows/lint.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 57dd7168..040c1f9e 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -128,6 +128,6 @@ jobs: with: mdbook-version: '0.4.35' - name: Install mdbook-keeper - run: cargo install mdbook-keeper --git https://github.com/tfpk/mddbook-keeper/ --rev 12f116d0840c69a6786dba3865768af3fde634f3 + run: cargo install mdbook-keeper --git https://github.com/tfpk/mdbook-keeper/ --rev 12f116d0840c69a6786dba3865768af3fde634f3 - name: Run mdbook build (tests all code snippets) run: CARGO_MANIFEST_DIR=. mdbook build book From 5b3f31330cd3d23a8c2063a4fc19963c18f8759d Mon Sep 17 00:00:00 2001 From: Trevor Lovell Date: Sat, 11 Nov 2023 16:54:27 -0700 Subject: [PATCH 5/8] docs: copy the getting started text from the README into the book --- book/src/getting-started.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/book/src/getting-started.md b/book/src/getting-started.md index 01cfd82a..00b4469c 100644 --- a/book/src/getting-started.md +++ b/book/src/getting-started.md @@ -1,3 +1,28 @@ +# Getting Started + +The goal of this plugin is to make it as easy as possible to use LDtk with bevy +for common use cases, while providing solutions to handle more difficult cases. +You only need a few things to get started: +1. Add the `LdtkPlugin` to the `App` +2. Insert the `LevelSelection` resource into the `App` to pick your level +3. Spawn an `LdtkWorldBundle` +4. Optionally, use `#[derive(LdtkEntity)]` and `#[derive(LdtkIntCell)]` on + bundles and register them to the `App` to automatically spawn those bundles + on Entity and IntGrid layers. + ```rust,no_run {{ #include ../../examples/basic.rs }} ``` + +There are other attributes available to `#[derive(LdtkEntity)]` and `#[derive(LdtkIntCell)]`, see the documentation for more details. + +By default, LDtk Entities and IntGrid tiles get spawned with `EntityInstance` +and `IntGridCell` components respectfully. +So, you can flesh out these entities in a system that queries for +`Added` or `Added` if you need more access to the +world, or if you just don't want to use the `LdtkEntity` and `LdtkIntCell` +traits. + +To load a new level, you can just update the `LevelSelection` resource. +Be sure to check out the `LdtkSettings` resource and the `LevelSet` component +for additional level-loading options. From 9e2a3b47600b1791e68400e4bead3ee06b2795f3 Mon Sep 17 00:00:00 2001 From: Trevor Lovell Date: Sun, 12 Nov 2023 13:15:37 -0700 Subject: [PATCH 6/8] docs: capitalize Bevy in getting started chapter --- book/src/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/getting-started.md b/book/src/getting-started.md index 00b4469c..08695bf3 100644 --- a/book/src/getting-started.md +++ b/book/src/getting-started.md @@ -1,6 +1,6 @@ # Getting Started -The goal of this plugin is to make it as easy as possible to use LDtk with bevy +The goal of this plugin is to make it as easy as possible to use LDtk with Bevy for common use cases, while providing solutions to handle more difficult cases. You only need a few things to get started: 1. Add the `LdtkPlugin` to the `App` From d1d1a077ae70de4cd66d5b12e8bebc8fa1081d7e Mon Sep 17 00:00:00 2001 From: Trevor Lovell Date: Sun, 12 Nov 2023 16:16:46 -0700 Subject: [PATCH 7/8] docs: move getting-started chapter into tutorials directory --- book/src/SUMMARY.md | 2 +- book/src/{ => tutorials}/getting-started.md | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename book/src/{ => tutorials}/getting-started.md (100%) diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index eb9f12c6..28efc6b9 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -2,7 +2,7 @@ [Introduction](README.md) # Tutorials -- [Getting Started](getting-started.md) +- [Getting Started](tutorials/getting-started.md) - [Sokoban]() - [Platformer]() # Explanation diff --git a/book/src/getting-started.md b/book/src/tutorials/getting-started.md similarity index 100% rename from book/src/getting-started.md rename to book/src/tutorials/getting-started.md From 855f98393562973c1496a7727508d3a26d87795d Mon Sep 17 00:00:00 2001 From: Trevor Lovell Date: Sun, 12 Nov 2023 16:18:49 -0700 Subject: [PATCH 8/8] docs: fix relative path to basic example in getting started chapter after move --- book/src/tutorials/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/tutorials/getting-started.md b/book/src/tutorials/getting-started.md index 08695bf3..bd0f1df7 100644 --- a/book/src/tutorials/getting-started.md +++ b/book/src/tutorials/getting-started.md @@ -11,7 +11,7 @@ You only need a few things to get started: on Entity and IntGrid layers. ```rust,no_run -{{ #include ../../examples/basic.rs }} +{{ #include ../../../examples/basic.rs }} ``` There are other attributes available to `#[derive(LdtkEntity)]` and `#[derive(LdtkIntCell)]`, see the documentation for more details.