Deploy Website with Github Pages (Related #776)

.github/workflows/website.yml

@@ -0,0 +1,120 @@
+name: Website
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+env:
+  RUSTFLAGS: -Cdebuginfo=0
+  CARGO_TERM_COLOR: always
+  CARGO_INCREMENTAL: 0
+  RUST_BACKTRACE: 1
+
+jobs:
+  Tutorials:
+    name: Doc Tutorials
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: docs/tutorials
+
+      - name: Build Books
+        uses: taiki-e/install-action@v2
+        with:
+          tool: [email protected]
+
+      - run: mdbook build docs/tutorials --dest-dir ${GITHUB_WORKSPACE}/public/docs/tutorials
+
+      - uses: actions/upload-artifact@v4
+        with:
+          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
+
+  Website:
+    name: Doc Website
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: |
+            docs/website
+
+      - 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.
+        run: echo "GITHUB_PAGES_URL=$(gh api "repos/$GITHUB_REPOSITORY/pages" --jq '.html_url')" >> $GITHUB_ENV
+
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: [email protected]
+
+      - 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
+
+  Deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    needs: [ Tutorials, 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 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

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

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
 

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.
 

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"
@@ -8,19 +8,21 @@ 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
 
 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"},
 ]

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<Self>;
+}
+
+#[derive(Debug)]
+struct Pos(f32);
+
+impl Component for Pos {
+    type Storage = VecStorage<Self>;
+}
+
+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::<Pos>();
+    world.register::<Vel>();
+
+    // 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.

docs/website/content/pages/docs.md

@@ -13,7 +13,3 @@ template = "page-nodate.html"
 
 * [Tutorials for master](tutorials/)
 
-## Reference
-
-* [Specs reference for master](reference/)
-

docs/website/themes/hyde/templates/index.html

@@ -39,7 +39,11 @@
                     <ul class="sidebar-nav">
                         {% block sidebar_nav %}
                         {% for link in config.extra.hyde_links %}
-                        <li class="sidebar-nav-item"><a href="{{ link.url }}">{{link.name}}</a></li>
+                        {% if link.absolut_url %}
+                        <li class="sidebar-nav-item"><a href="{{ link.absolut_url }}">{{link.name}}</a></li>
+                        {% else %}
+                        <li class="sidebar-nav-item"><a href="{{ config.base_url }}{{ link.url }}">{{link.name}}</a></li>
+                        {% endif %}
                         {% endfor %}
                         {% endblock sidebar_nav %}
                     </ul>

docs/website/themes/hyde/templates/section-nodate.html

@@ -0,0 +1,9 @@
+{% extends "index.html" %}
+
+{% block content %}
+<div class="post">
+  <h1 class="post-title">{{ section.title }}</h1>
+  {{ section.content | safe }}
+</div>
+{% endblock content %}
+