From 08abbb622ad2cf76fc1498462244292ae5a5c62b Mon Sep 17 00:00:00 2001 From: "Claas j. Gramann" Date: Thu, 2 May 2024 23:57:04 +0200 Subject: [PATCH 01/10] Add workflow to build reference and tutorials --- .github/workflows/website.yml | 43 +++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 .github/workflows/website.yml diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml new file mode 100644 index 000000000..6f307cd71 --- /dev/null +++ b/.github/workflows/website.yml @@ -0,0 +1,43 @@ +name: Website + +on: + push: + branches: + - master + pull_request: + +env: + RUSTFLAGS: -Cdebuginfo=0 + CARGO_TERM_COLOR: always + CARGO_INCREMENTAL: 0 + RUST_BACKTRACE: 1 + +jobs: + Ref-and-Tutorial: + name: Doc Reference + Tutorials + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + sparse-checkout: | + docs/reference + docs/tutorials + + - name: Build Books + uses: taiki-e/install-action@v2 + with: + tool: mdbook@0.4.37 + + - run: mdbook build docs/reference --dest-dir ${GITHUB_WORKSPACE}/public/docs/reference + - run: mdbook build docs/tutorials --dest-dir ${GITHUB_WORKSPACE}/public/docs/tutorials + + - uses: actions/upload-artifact@v4 + with: + name: Doc Reference + path: | + public/docs/reference + - uses: actions/upload-artifact@v4 + with: + name: Doc Tutorials + path: | + public/docs/tutorials From 464dfe46684580273c95cab640b4548a9c72b685 Mon Sep 17 00:00:00 2001 From: "Claas j. Gramann" Date: Thu, 2 May 2024 23:58:19 +0200 Subject: [PATCH 02/10] Add job to build Rust API Docs --- .github/workflows/website.yml | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index 6f307cd71..4be630d00 100644 --- a/.github/workflows/website.yml +++ b/.github/workflows/website.yml @@ -41,3 +41,27 @@ jobs: name: Doc Tutorials path: | public/docs/tutorials + + Rust-API: + name: Doc Rust API + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions-rs/toolchain@v1 + with: + toolchain: stable + profile: minimal + override: true + components: rust-docs + + - name: Build API Doc + env: + FEATURES: parallel serde derive uuid_entity storage-event-control + run: cargo doc --all --features "${FEATURES}" # --no-deps + + - uses: actions/upload-artifact@v4 + with: + name: Doc Rust API + path: | + target/doc From fc704cba9be019dc022e69ba6711bd30f4add48c Mon Sep 17 00:00:00 2001 From: "Claas j. Gramann" Date: Thu, 2 May 2024 23:59:29 +0200 Subject: [PATCH 03/10] Add job to build Website --- .github/workflows/website.yml | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index 4be630d00..59dcf7a14 100644 --- a/.github/workflows/website.yml +++ b/.github/workflows/website.yml @@ -65,3 +65,30 @@ jobs: name: Doc Rust API path: | target/doc + + Website: + name: Doc Website + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + sparse-checkout: | + docs/website + + - name: Set Build Flags + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # Use the API to retrieve the github pages url and set an environment variable containing the value. + run: echo "GITHUB_PAGES_URL=$(gh api "repos/$GITHUB_REPOSITORY/pages" --jq '.html_url')" >> $GITHUB_ENV + + - uses: taiki-e/install-action@v2 + with: + tool: zola@0.18.0 + + - run: zola build --base-url $GITHUB_PAGES_URL + working-directory: docs/website + + - uses: actions/upload-artifact@v4 + with: + name: Doc Zola + path: docs/website/public From 1b0ba07aef2f1d8956e27177e92950f61b2f9630 Mon Sep 17 00:00:00 2001 From: "Claas j. Gramann" Date: Fri, 3 May 2024 00:03:12 +0200 Subject: [PATCH 04/10] Add job to deploy to github pages --- .github/workflows/website.yml | 40 +++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index 59dcf7a14..202f946f1 100644 --- a/.github/workflows/website.yml +++ b/.github/workflows/website.yml @@ -92,3 +92,43 @@ jobs: with: name: Doc Zola path: docs/website/public + + Deploy: + name: Deploy + runs-on: ubuntu-latest + needs: [Ref-and-Tutorial, Rust-API, Website] + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + if: github.event_name != 'pull_request' + steps: + - uses: actions/download-artifact@v4 + with: + name: Doc Reference + path: public/docs/reference + + - uses: actions/download-artifact@v4 + with: + name: Doc Tutorials + path: public/docs/tutorials + + - uses: actions/download-artifact@v4 + with: + name: Doc Rust API + path: public/docs/api + + - uses: actions/download-artifact@v4 + with: + name: Doc Zola + path: public + + - uses: actions/upload-pages-artifact@v3 + with: + path: public + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 From 95435dd22696bcc536f0048a2528289468b3f472 Mon Sep 17 00:00:00 2001 From: "Claas j. Gramann" Date: Fri, 3 May 2024 02:16:11 +0200 Subject: [PATCH 05/10] Remove netlify --- netlify.toml | 8 ------- scripts/build-netlify.sh | 48 ---------------------------------------- 2 files changed, 56 deletions(-) delete mode 100644 netlify.toml delete mode 100755 scripts/build-netlify.sh diff --git a/netlify.toml b/netlify.toml deleted file mode 100644 index 511434346..000000000 --- a/netlify.toml +++ /dev/null @@ -1,8 +0,0 @@ -[build] -publish = "public" -command = "BASE_URL=\"https://specs.netlify.com\" ./scripts/build-netlify.sh" - -[build.environment] - -[context.deploy-preview] -command = "BASE_URL=${DEPLOY_PRIME_URL} ./scripts/build-netlify.sh" diff --git a/scripts/build-netlify.sh b/scripts/build-netlify.sh deleted file mode 100755 index 8c1c2de88..000000000 --- a/scripts/build-netlify.sh +++ /dev/null @@ -1,48 +0,0 @@ -#!/bin/sh - -set -e - -WORKING_DIR=$(pwd) - -# Install everything -mkdir bin -cd bin -install_tar_gz() { - curl -sL "$1" | tar zxv -} - -echo "Installing dependencies..." - -install_tar_gz https://github.com/getzola/zola/releases/download/v0.6.0/zola-v0.6.0-x86_64-unknown-linux-gnu.tar.gz -install_tar_gz https://github.com/rust-lang-nursery/mdBook/releases/download/v0.2.1/mdbook-v0.2.1-x86_64-unknown-linux-gnu.tar.gz -BIN_DIR=$(pwd) - -curl https://sh.rustup.rs -sSf | sh -s - --default-toolchain nightly -y -. ~/.cargo/env - -# Build website -echo "Building website..." - -cd "${WORKING_DIR}"/docs/website -"${BIN_DIR}"/zola build --base-url "${BASE_URL}" -o "${WORKING_DIR}/public" - -# Build reference + tutorials -build_book() { - cd "${WORKING_DIR}"/docs/$1 - "${BIN_DIR}"/mdbook build -d "${WORKING_DIR}/public/docs/$1" -} - -echo "Building books..." - -build_book reference -build_book tutorials - -# Build API docs -FEATURES="parallel serde derive uuid_entity" - -echo "Building Rust API docs..." -cd "${WORKING_DIR}" -cargo doc --all --features "${FEATURES}" || cargo doc --all --features "${FEATURES}" --no-deps -cp -R target/doc "${WORKING_DIR}/public/docs/api" - -echo "Done!" From e5a213c4e694a50ad4359f2525beab4d8c8d434a Mon Sep 17 00:00:00 2001 From: "Claas j. Gramann" Date: Fri, 3 May 2024 04:14:12 +0200 Subject: [PATCH 06/10] Website: Fix links for deployment in sub folders Update base-url, because it will be overwritten in every case. --- docs/website/config.toml | 9 ++++----- docs/website/themes/hyde/templates/index.html | 6 +++++- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/website/config.toml b/docs/website/config.toml index e54d05c94..34a3fc6fa 100644 --- a/docs/website/config.toml +++ b/docs/website/config.toml @@ -1,5 +1,5 @@ -# The URL the site will be built for -base_url = "https://slide-rs.github.io/" +# Should be supplied with --base-url +base_url = "/" title = "Specs" description = "Specs Parallel ECS, a Rust library for parallel data processing using the Entity Component System pattern" @@ -19,8 +19,7 @@ taxonomies = [] [extra] hyde_links = [ - {url = "/", name = "Home"}, + {url = ".", name = "Home"}, {url = "docs", name = "Docs"}, - {url = "https://github.com/slide-rs/specs", name = "GitHub"}, -# {url = "about", name = "About"}, + {absolut_url = "https://github.com/amethyst/specs", name = "GitHub"}, ] diff --git a/docs/website/themes/hyde/templates/index.html b/docs/website/themes/hyde/templates/index.html index f96dc11b9..5b9873840 100644 --- a/docs/website/themes/hyde/templates/index.html +++ b/docs/website/themes/hyde/templates/index.html @@ -39,7 +39,11 @@
    {% block sidebar_nav %} {% for link in config.extra.hyde_links %} -
  • {{link.name}}
    • + {% if link.absolut_url %} +
  • {{link.name}}
    • + {% else %} +
  • {{link.name}}
    • + {% endif %} {% endfor %} {% endblock sidebar_nav %}
From f3ffaf4ee961880c7d6a928d454dad4f23be8c9e Mon Sep 17 00:00:00 2001 From: "Claas j. Gramann" Date: Fri, 3 May 2024 02:09:12 +0200 Subject: [PATCH 07/10] Website: Remove references Remove: About and unused sites --- .github/workflows/website.yml | 24 +++++------------------- docs/reference/book.toml | 5 ----- docs/reference/src/01_system.md | 4 ---- docs/reference/src/SUMMARY.md | 5 ----- docs/reference/src/intro.md | 7 ------- docs/tutorials/src/01_intro.md | 4 ---- docs/website/content/pages/about.md | 8 -------- docs/website/content/pages/docs.md | 4 ---- docs/website/content/specs-0.15.md | 10 ---------- 9 files changed, 5 insertions(+), 66 deletions(-) delete mode 100644 docs/reference/book.toml delete mode 100644 docs/reference/src/01_system.md delete mode 100644 docs/reference/src/SUMMARY.md delete mode 100644 docs/reference/src/intro.md delete mode 100644 docs/website/content/pages/about.md delete mode 100644 docs/website/content/specs-0.15.md diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index 202f946f1..c8e88c4b8 100644 --- a/.github/workflows/website.yml +++ b/.github/workflows/website.yml @@ -13,34 +13,25 @@ env: RUST_BACKTRACE: 1 jobs: - Ref-and-Tutorial: - name: Doc Reference + Tutorials + Tutorials: + name: Doc Tutorials runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: - sparse-checkout: | - docs/reference - docs/tutorials + sparse-checkout: docs/tutorials - name: Build Books uses: taiki-e/install-action@v2 with: tool: mdbook@0.4.37 - - run: mdbook build docs/reference --dest-dir ${GITHUB_WORKSPACE}/public/docs/reference - run: mdbook build docs/tutorials --dest-dir ${GITHUB_WORKSPACE}/public/docs/tutorials - - uses: actions/upload-artifact@v4 - with: - name: Doc Reference - path: | - public/docs/reference - uses: actions/upload-artifact@v4 with: name: Doc Tutorials - path: | - public/docs/tutorials + path: public/docs/tutorials Rust-API: name: Doc Rust API @@ -96,7 +87,7 @@ jobs: Deploy: name: Deploy runs-on: ubuntu-latest - needs: [Ref-and-Tutorial, Rust-API, Website] + needs: [ Tutorials, Rust-API, Website ] permissions: pages: write id-token: write @@ -105,11 +96,6 @@ jobs: url: ${{ steps.deployment.outputs.page_url }} if: github.event_name != 'pull_request' steps: - - uses: actions/download-artifact@v4 - with: - name: Doc Reference - path: public/docs/reference - - uses: actions/download-artifact@v4 with: name: Doc Tutorials diff --git a/docs/reference/book.toml b/docs/reference/book.toml deleted file mode 100644 index 094303ccb..000000000 --- a/docs/reference/book.toml +++ /dev/null @@ -1,5 +0,0 @@ -[book] -authors = ["Thomas Schaller"] -multilingual = false -src = "src" -title = "Specs reference" diff --git a/docs/reference/src/01_system.md b/docs/reference/src/01_system.md deleted file mode 100644 index f44ce8afb..000000000 --- a/docs/reference/src/01_system.md +++ /dev/null @@ -1,4 +0,0 @@ -# System - - - diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md deleted file mode 100644 index ab94c79ec..000000000 --- a/docs/reference/src/SUMMARY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Summary - -- [Introduction](./intro.md) -- [1. System](./01_system.md) - diff --git a/docs/reference/src/intro.md b/docs/reference/src/intro.md deleted file mode 100644 index 7dc485678..000000000 --- a/docs/reference/src/intro.md +++ /dev/null @@ -1,7 +0,0 @@ -# Specs Parallel ECS - -This is the reference for Specs, a Rust Entity Component System library. - -If you're looking for tutorials instead, there's a book for that -[here](../tutorials/), too. - diff --git a/docs/tutorials/src/01_intro.md b/docs/tutorials/src/01_intro.md index e2982554b..fa4d1db3e 100644 --- a/docs/tutorials/src/01_intro.md +++ b/docs/tutorials/src/01_intro.md @@ -15,10 +15,6 @@ Additional documentation is available on `docs.rs`: * [API documentation for Specs](https://docs.rs/specs) -There also is a reference-style documentation available here: - -* [Specs reference](../reference/) - You don't yet know what an ECS is all about? The next section is for you! In case you already know what an ECS is, just skip it. diff --git a/docs/website/content/pages/about.md b/docs/website/content/pages/about.md deleted file mode 100644 index 813b0ea01..000000000 --- a/docs/website/content/pages/about.md +++ /dev/null @@ -1,8 +0,0 @@ -+++ -title = "About" -path = "about" -template = "page-nodate.html" -+++ - -This site is about Specs. - diff --git a/docs/website/content/pages/docs.md b/docs/website/content/pages/docs.md index 234bf940a..5ebc2b0aa 100644 --- a/docs/website/content/pages/docs.md +++ b/docs/website/content/pages/docs.md @@ -13,7 +13,3 @@ template = "page-nodate.html" * [Tutorials for master](tutorials/) -## Reference - -* [Specs reference for master](reference/) - diff --git a/docs/website/content/specs-0.15.md b/docs/website/content/specs-0.15.md deleted file mode 100644 index 1c26d9bcf..000000000 --- a/docs/website/content/specs-0.15.md +++ /dev/null @@ -1,10 +0,0 @@ -+++ -title = "Specs 0.15 released" -date = 2019-05-04 -draft = true -+++ - -Specs 0.15 finally released! - -Test - From e527fa4dcf8197a968e3ad21705f4d4c7f17d6dc Mon Sep 17 00:00:00 2001 From: "Claas j. Gramann" Date: Fri, 3 May 2024 03:33:36 +0200 Subject: [PATCH 08/10] Website: index from parts of README.md --- docs/website/config.toml | 3 + docs/website/content/_index.md | 100 +++++++++++++++++- docs/website/themes/hyde/templates/page.html | 10 -- .../themes/hyde/templates/section-nodate.html | 9 ++ 4 files changed, 110 insertions(+), 12 deletions(-) delete mode 100644 docs/website/themes/hyde/templates/page.html create mode 100644 docs/website/themes/hyde/templates/section-nodate.html diff --git a/docs/website/config.toml b/docs/website/config.toml index 34a3fc6fa..1ba785f72 100644 --- a/docs/website/config.toml +++ b/docs/website/config.toml @@ -8,10 +8,13 @@ theme = "hyde" # Whether to automatically compile all Sass files in the sass directory compile_sass = true +[markdown] # Whether to do syntax highlighting # Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola highlight_code = true +highlight_theme = "inspired-github" + # Whether to build a search index to be used later on by a JavaScript library build_search_index = true diff --git a/docs/website/content/_index.md b/docs/website/content/_index.md index ff6d02b7f..f0da41e78 100644 --- a/docs/website/content/_index.md +++ b/docs/website/content/_index.md @@ -1,5 +1,101 @@ +++ -paginate_by = 5 -sort_by = "date" +title = "Specs" +template = "section-nodate.html" +++ +> **S**pecs **P**arallel **ECS** + +Specs is an Entity-Component System written in Rust. +Unlike most other ECS libraries out there, it provides + +* easy parallelism +* high flexibility + * contains 5 different storages for components, which can be extended by the user + * its types are mostly not coupled, so you can easily write some part yourself and + still use Specs + * `System`s may read from and write to components and resources, can depend on each + other and you can use barriers to force several stages in system execution +* high performance for real-world applications + +## [Link to the book][book] + +[book]: docs/tutorials/ + +## Example + +```rust +use specs::prelude::*; + +// A component contains data +// which is associated with an entity. +#[derive(Debug)] +struct Vel(f32); + +impl Component for Vel { + type Storage = VecStorage; +} + +#[derive(Debug)] +struct Pos(f32); + +impl Component for Pos { + type Storage = VecStorage; +} + +struct SysA; + +impl<'a> System<'a> for SysA { + // These are the resources required for execution. + // You can also define a struct and `#[derive(SystemData)]`, + // see the `full` example. + type SystemData = (WriteStorage<'a, Pos>, ReadStorage<'a, Vel>); + + fn run(&mut self, (mut pos, vel): Self::SystemData) { + // The `.join()` combines multiple component storages, + // so we get access to all entities which have + // both a position and a velocity. + for (pos, vel) in (&mut pos, &vel).join() { + pos.0 += vel.0; + } + } +} + +fn main() { + // The `World` is our + // container for components + // and other resources. + let mut world = World::new(); + world.register::(); + world.register::(); + + // An entity may or may not contain some component. + + world.create_entity().with(Vel(2.0)).with(Pos(0.0)).build(); + world.create_entity().with(Vel(4.0)).with(Pos(1.6)).build(); + world.create_entity().with(Vel(1.5)).with(Pos(5.4)).build(); + + // This entity does not have `Vel`, so it won't be dispatched. + world.create_entity().with(Pos(2.0)).build(); + + // This builds a dispatcher. + // The third parameter of `with` specifies + // logical dependencies on other systems. + // Since we only have one, we don't depend on anything. + // See the `full` example for dependencies. + let mut dispatcher = DispatcherBuilder::new() + .with(SysA, "sys_a", &[]).build(); + // This will call the `setup` function of every system. + // In this example this has no effect + // since we already registered our components. + dispatcher.setup(&mut world); + + // This dispatches all the systems in parallel (but blocking). + dispatcher.dispatch(&mut world); +} +``` + +## Contribution + +Contribution is very welcome! If you didn't contribute before, +just filter for issues with "easy" or "good first issue" label. +Please note that your contributions are assumed to be dual-licensed under Apache-2.0/MIT. \ No newline at end of file diff --git a/docs/website/themes/hyde/templates/page.html b/docs/website/themes/hyde/templates/page.html deleted file mode 100644 index 35acc9731..000000000 --- a/docs/website/themes/hyde/templates/page.html +++ /dev/null @@ -1,10 +0,0 @@ -{% extends "index.html" %} - -{% block content %} -
-

{{ page.title }}

- {{ page.date | date(format="%Y-%m-%d") }} - {{ page.content | safe }} -
-{% endblock content %} - diff --git a/docs/website/themes/hyde/templates/section-nodate.html b/docs/website/themes/hyde/templates/section-nodate.html new file mode 100644 index 000000000..0b12a948b --- /dev/null +++ b/docs/website/themes/hyde/templates/section-nodate.html @@ -0,0 +1,9 @@ +{% extends "index.html" %} + +{% block content %} +
+

{{ section.title }}

+ {{ section.content | safe }} +
+{% endblock content %} + From 25f5c614a42858289e7239544e58a489175d9d3d Mon Sep 17 00:00:00 2001 From: "Claas j. Gramann" Date: Fri, 3 May 2024 03:50:06 +0200 Subject: [PATCH 09/10] Fix readme crates io/rs links --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index a5caf0a4b..b532f2440 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ Minimum Rust version: 1.70 ## [Link to the book][book] -[book]: https://specs.amethyst.rs/docs/tutorials/ +[book]: https://amethyst.github.io/specs/docs/tutorials/ ## Example @@ -118,10 +118,10 @@ Please look into [the examples directory](examples) for more. | crate | version | |----------|------------------------------------------------------------------------------------------------| -| hibitset | [![hibitset](https://img.shields.io/crates/v/hibitset.svg)](https://crates.rs/crates/hibitset) | -| rayon | [![rayon](https://img.shields.io/crates/v/rayon.svg)](https://crates.rs/crates/rayon) | -| shred | [![shred](https://img.shields.io/crates/v/shred.svg)](https://crates.rs/crates/shred) | -| shrev | [![shrev](https://img.shields.io/crates/v/shrev.svg)](https://crates.rs/crates/shrev) | +| hibitset | [![hibitset](https://img.shields.rs/crates/v/hibitset.svg)](https://crates.rs/crates/hibitset) | +| rayon | [![rayon](https://img.shields.rs/crates/v/rayon.svg)](https://crates.rs/crates/rayon) | +| shred | [![shred](https://img.shields.rs/crates/v/shred.svg)](https://crates.rs/crates/shred) | +| shrev | [![shrev](https://img.shields.rs/crates/v/shrev.svg)](https://crates.rs/crates/shrev) | ## Contribution From b6c2509975ea87c2a35bc275ea8dc947fd34d989 Mon Sep 17 00:00:00 2001 From: "Claas j. Gramann" Date: Sun, 5 May 2024 01:58:24 +0200 Subject: [PATCH 10/10] Update links to website and repo --- .github/workflows/website.yml | 2 +- Cargo.toml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index c8e88c4b8..a3a584083 100644 --- a/.github/workflows/website.yml +++ b/.github/workflows/website.yml @@ -66,7 +66,7 @@ jobs: sparse-checkout: | docs/website - - name: Set Build Flags + - name: Find Base Url env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Use the API to retrieve the github pages url and set an environment variable containing the value. diff --git a/Cargo.toml b/Cargo.toml index e58ed3fff..a0904e688 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -5,8 +5,8 @@ description = """ Specs is an Entity-Component-System library written in Rust. """ documentation = "https://docs.rs/specs/" -repository = "https://github.com/slide-rs/specs" -homepage = "https://specs.amethyst.rs" +repository = "https://github.com/amethyst/specs" +homepage = "https://amethyst.github.io/specs" readme = "README.md" keywords = ["gamedev", "ecs", "entity", "component"] categories = ["concurrency", "game-engines"]