Add mdbook and GitHub pages deployment

.github/workflows/docs.yml

@@ -3,19 +3,25 @@ on:
   push:
     branches:
       - main
+    tags:
+      - "v*" # Push events to matching v*, i.e. v1.0, v20.15.10
 jobs:
   build:
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v2
+        with:
+            submodules: true
+      - run: export SNAPSHOT=`echo "${{ github.ref }}" | sed 's|/ref/.*/||'`
+      - run: export DOCS_DIR="docs-build/$SNAPSHOT"
       - run: brew install mdbook
       - run: mkdir docs-build/
-      - run: $(cd docs && mdbook build -d ../docs-build/book)
+      - run: $(cd docs && mdbook build -d ../$DOCS_DIR/book)
       - run: cargo doc --workspace --no-deps
-      - run: mv target/doc docs-build/api
+      - run: mv target/doc $DOCS_DIR/api
       - uses: JamesIves/github-pages-deploy-action@4.1.4
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          BRANCH: gh-pages # The branch the action should deploy to.
-          FOLDER: docs-build # The folder the action should deploy.
-          CLEAN: true # Automatically remove deleted files from the deploy branch
+          BRANCH: gh-pages
+          FOLDER: docs-build
+          CLEAN: false

docs/book.toml

@@ -1,6 +1,7 @@
 [book]
-authors = ["Erin Power"]
 language = "en"
 multilingual = false
 src = "src"
 title = "Quilkin Book"
+
+[output.html]

docs/src/SUMMARY.md

@@ -6,9 +6,17 @@
     - [Agones + Xonotic](./quickstart-agones-xonotic.md)
 - [Usage](./using.md)
 - [Session](./session.md)
-- [Integrations](./integrations.md)
 - [Proxy](./proxy.md)
     - [Proxy Configuration](./proxy-configuration.md)
+- [Filters](./filters.md)
+    - [Capture Bytes](./filters/capture_bytes.md)
+    - [Compress](./filters/compress.md)
+    - [Debug](./filters/debug.md)
+    - [Load Balancer](./filters/load_balancer.md)
+    - [Local Rate Limit](./filters/local_rate_limit.md)
+    - [Token Router](./filters/token_router.md)
+    - [Writing Custom Filters](./filters/writing_custom_filters.md)
+- [Integrations](./integrations.md)
 - [Administration](./admin.md)
 - [FAQ](./FAQ.md)
 - [xDS](./xds.md)

docs/extensions/filters/writing_custom_filters.md → docs/src/filters/writing_custom_filters.md

@@ -1,3 +1,5 @@
+# Writing Custom Filters
+
 Quilkin provides an extensible implementation of [Filters] that allows us to plug in custom implementations to fit our needs.
 This document provides an overview of the API and how we can go about writing our own [Filters].
 

docs/src/integrations.md

@@ -8,7 +8,7 @@ on how you can use Quilkin in your multiplayer game networking architecture.
 
 ## Server Proxy as a Sidecar
 
-```
+```text
                   +
                   |
                Internet
@@ -49,7 +49,7 @@ and metric information that comes with Quilkin.
 
 ## Client Proxy to Sidecar Server Proxy
 
-```
+```text
                                     +
                                     |
                                  Internet
@@ -85,7 +85,7 @@ advantage of Client Proxy functionality.
 
 ## Client Proxy to Separate Server Proxies Pools
 
-```
+```text
                                        +                          +
                                        |                          |
                                     Internet                   Private
@@ -134,9 +134,9 @@ while also providing the most redundancy and security for your dedicated game se
 
 ## What Next?
 
-* Have a look at the [example configurations](../examples) for basic configuration examples.
+* Have a look at the [example configurations](https://github.com/googleforgames/quilkin/blob/main/examples) for basic configuration examples.
 * Review the [set of filters](./extensions/filters/filters.md) that are available.
 
 ---
 
-Diagrams powered by http://asciiflow.com/
+Diagrams powered by http://asciiflow.com/

docs/src/introduction.md

@@ -11,7 +11,7 @@ It is designed to be used behind game clients as well as in front of dedicated g
 
 Quilkin's aim is to pull the above functionality out of bespoke, monolithic dedicated game servers and clients, and
 provide standard, composable modules that can be reused across a wide set of multiplayer games, so that game
-developers can instead focus on their game specific aspects of building a multiplayer game.  
+developers can instead focus on their game specific aspects of building a multiplayer game.
 
 ## Why use Quilkin?
 
@@ -33,12 +33,12 @@ Quilkin incorporates these abilities:
 * Non-transparent proxying of UDP data, the internal state of your game architecture is not visible to bad actors.
 * Out of the box metrics for UDP packet information.
 * Composable tools for access control and security.
-* Able to be utilised as a standalone binary, with no client/server changes required or as a Rust library 
+* Able to be utilised as a standalone binary, with no client/server changes required or as a Rust library
   depending on how deep an integration you wish for your system.
 * Can be integrated with C/C++ code bases via FFI.
 
 ## What Next?
 
 * Read the [usage guide](./using.md)
-* Have a look at the [example configurations](../examples) for basic configuration examples.
+* Have a look at the [example configurations](https://github.com/googleforgames/quilkin/blob/main/examples) for basic configuration examples.
 * Check out the [example integration patterns](./integrations.md).

docs/src/proxy-configuration.md

@@ -108,5 +108,5 @@ definitions:
         - address
 ```
 
-[examples]: ../examples
+[examples]: https://github.com/googleforgames/quilkin/blob/main/examples
 

docs/src/quickstart-agones-xonotic.md

@@ -53,7 +53,7 @@ Let's take a look at some metrics that Quilkin outputs.
 Grab the name of the GameServer you connected to before, and replace the `${gameserver}` value below, and run the 
 command. This will forward the [admin](./admin.md) interface to localhost.
 
-```
+```shell
 kubectl port-forward ${gameserver} 9091
 ```
 
@@ -132,5 +132,5 @@ kubectl delete -f https://raw.githubusercontent.com/googleforgames/quilkin/main/
 
 ## What's Next?
 
-* Have a look at the [examples](./examples) folder for configuration and usage examples.
-* Explore the [proxy configuration reference](./docs/proxy-configuration.md) for other configuration options. 
+* Have a look at the [examples](https://github.com/googleforgames/quilkin/blob/main/examples) folder for configuration and usage examples.
+* Explore the [proxy configuration reference](./docs/proxy-configuration.md) for other configuration options. 

docs/src/quickstart-netcat.md

@@ -2,7 +2,7 @@
 
 ## Requirements
 
-* A *nix terminal
+* A \*nix terminal
 * A binary release of Quilkin from the [Github releases page](https://github.com/googleforgames/quilkin/releases)
 * [ncat](https://nmap.org/ncat/guide/)
 * [netcat](http://netcat.sourceforge.net/)
@@ -32,7 +32,7 @@ static:
     - address: 127.0.0.1:8000
 ```
 
-This configuration will start Quilkin on the default port of 7000, and it will redirect all incoming UDP traffic to 
+This configuration will start Quilkin on the default port of 7000, and it will redirect all incoming UDP traffic to
 a single endpoint of 127.0.0.1, port 8000.
 
 Let's start Quilkin with the above configuration:
@@ -75,6 +75,6 @@ Congratulations! You have successfully routed a UDP packet and back again with Q
 What's next?
 
 * Run through the [Quilkin with Agones quickstart](./quickstart-agones-xonotic.md).
-* Have a look at some of [the examples](../examples) we have.
-* Check out the [proxy configuration reference](./proxy-configuration.md) to what other configuration options are 
+* Have a look at some of [the examples](https://github.com/googleforgames/quilkin/blob/main/examples) we have.
+* Check out the [proxy configuration reference](./proxy-configuration.md) to what other configuration options are
   available.

src/lib.rs

@@ -36,15 +36,15 @@ mod external_doc_tests {
     // https://github.com/rust-lang/rust/issues/85882
     macro_rules! hide {
         () => {
-            #[doc = include_str!("../docs/extensions/filters/filters.md")]
-            #[doc = include_str!("../docs/extensions/filters/writing_custom_filters.md")]
-            #[doc = include_str!("../docs/extensions/filters/load_balancer.md")]
-            #[doc = include_str!("../docs/extensions/filters/local_rate_limit.md")]
-            #[doc = include_str!("../docs/extensions/filters/debug.md")]
-            #[doc = include_str!("../docs/extensions/filters/concatenate_bytes.md")]
-            #[doc = include_str!("../docs/extensions/filters/capture_bytes.md")]
-            #[doc = include_str!("../docs/extensions/filters/token_router.md")]
-            #[doc = include_str!("../docs/extensions/filters/compress.md")]
+            #[doc = include_str!("../docs/src/extensions/filters/filters.md")]
+            #[doc = include_str!("../docs/src/extensions/filters/writing_custom_filters.md")]
+            #[doc = include_str!("../docs/src/extensions/filters/load_balancer.md")]
+            #[doc = include_str!("../docs/src/extensions/filters/local_rate_limit.md")]
+            #[doc = include_str!("../docs/src/extensions/filters/debug.md")]
+            #[doc = include_str!("../docs/src/extensions/filters/concatenate_bytes.md")]
+            #[doc = include_str!("../docs/src/extensions/filters/capture_bytes.md")]
+            #[doc = include_str!("../docs/src/extensions/filters/token_router.md")]
+            #[doc = include_str!("../docs/src/extensions/filters/compress.md")]
             mod tests {}
         };
     }