ci: add "Build and test book" job and basic getting started chapter

.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/mdbook-keeper/ --rev 12f116d0840c69a6786dba3865768af3fde634f3
+      - name: Run mdbook build (tests all code snippets)
+        run: CARGO_MANIFEST_DIR=. mdbook build book

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"]

book/src/SUMMARY.md

@@ -2,7 +2,7 @@
 
 [Introduction](README.md)
 # Tutorials
-- [Getting Started]()
+- [Getting Started](tutorials/getting-started.md)
 - [Sokoban]()
 - [Platformer]()
 # Explanation

book/src/tutorials/getting-started.md

@@ -0,0 +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<EntityInstance>` or `Added<IntGridCell>` 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.