Add mdbook and GitHub pages deployment (#319)

Co-authored-by: Mark Mandel <[email protected]>
googleforgames · Aug 10, 2021 · c187b5a · c187b5a
1 parent 4d0bd0d
commit c187b5a
Show file tree

Hide file tree

Showing 25 changed files with 86 additions and 25 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,29 @@
+name: Deploy docs
+on:
+  push:
+    branches:
+      - main
+      - pr/** # just for testing
+    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: echo snapshot=$(echo ${{ github.ref }} | sed -E 's|refs/[^/]+/||') >> $GITHUB_ENV
+      - run: echo docs_dir=docs-build/${{ env.snapshot }} >> $GITHUB_ENV
+      - run: echo documentation directory=${{ env.docs_dir }}
+      - run: brew install mdbook
+      - run: mkdir -p ${{ env.docs_dir }}
+      - run: $(cd docs && mdbook build -d ../${{ env.docs_dir }}/book)
+      - run: cargo doc --workspace --no-deps
+      - run: mv target/doc ${{ env.docs_dir }}/api
+      - uses: JamesIves/[email protected]
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages
+          FOLDER: docs-build
+          CLEAN: false
diff --git a/.gitignore b/.gitignore
@@ -28,6 +28,7 @@ dependencies-src.zip
 quilkin-*.zip
 
 /quilkin.yaml
+/docs/book
 
 ### Rust template
 # Generated by Cargo

diff --git a/docs/book.toml b/docs/book.toml
@@ -0,0 +1,7 @@
+[book]
+language = "en"
+multilingual = false
+src = "src"
+title = "Quilkin Book"
+
+[output.html]
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -0,0 +1,22 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Quickstart]()
+    - [Netcat](./quickstart-netcat.md)
+    - [Agones + Xonotic](./quickstart-agones-xonotic.md)
+- [Usage](./using.md)
+- [Session](./session.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)
diff --git a/docs/admin.md → docs/src/admin.md b/docs/admin.md → docs/src/admin.md
diff --git a/docs/faq.md → docs/src/faq.md b/docs/faq.md → docs/src/faq.md
diff --git a/docs/extensions/filters/filters.md → docs/src/filters.md b/docs/extensions/filters/filters.md → docs/src/filters.md
diff --git a/docs/extensions/filters/capture_bytes.md → docs/src/filters/capture_bytes.md b/docs/extensions/filters/capture_bytes.md → docs/src/filters/capture_bytes.md
diff --git a/docs/extensions/filters/compress.md → docs/src/filters/compress.md b/docs/extensions/filters/compress.md → docs/src/filters/compress.md
diff --git a/docs/extensions/filters/concatenate_bytes.md → docs/src/filters/concatenate_bytes.md b/docs/extensions/filters/concatenate_bytes.md → docs/src/filters/concatenate_bytes.md
diff --git a/docs/extensions/filters/debug.md → docs/src/filters/debug.md b/docs/extensions/filters/debug.md → docs/src/filters/debug.md
diff --git a/docs/extensions/filters/load_balancer.md → docs/src/filters/load_balancer.md b/docs/extensions/filters/load_balancer.md → docs/src/filters/load_balancer.md
diff --git a/docs/extensions/filters/local_rate_limit.md → docs/src/filters/local_rate_limit.md b/docs/extensions/filters/local_rate_limit.md → docs/src/filters/local_rate_limit.md
diff --git a/docs/extensions/filters/token_router.md → docs/src/filters/token_router.md b/docs/extensions/filters/token_router.md → docs/src/filters/token_router.md
diff --git a/...ensions/filters/writing_custom_filters.md → docs/src/filters/writing_custom_filters.md b/...ensions/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].
 

diff --git a/docs/integrations.md → docs/src/integrations.md b/docs/integrations.md → 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/
diff --git a/docs/README.md → docs/src/introduction.md b/docs/README.md → 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).
diff --git a/docs/proxy-configuration.md → docs/src/proxy-configuration.md b/docs/proxy-configuration.md → docs/src/proxy-configuration.md
@@ -108,5 +108,5 @@ definitions:
         - address
 ```
 
-[examples]: ../examples
+[examples]: https://github.com/googleforgames/quilkin/blob/main/examples
 
diff --git a/docs/proxy.md → docs/src/proxy.md b/docs/proxy.md → docs/src/proxy.md
diff --git a/docs/quickstart-agones-xonotic.md → docs/src/quickstart-agones-xonotic.md b/docs/quickstart-agones-xonotic.md → 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. 
diff --git a/docs/quickstart-netcat.md → docs/src/quickstart-netcat.md b/docs/quickstart-netcat.md → 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.
diff --git a/docs/session.md → docs/src/session.md b/docs/session.md → docs/src/session.md
diff --git a/docs/using.md → docs/src/using.md b/docs/using.md → docs/src/using.md
diff --git a/docs/xds.md → docs/src/xds.md b/docs/xds.md → docs/src/xds.md
diff --git a/src/lib.rs b/src/lib.rs
@@ -39,13 +39,13 @@ pub use quilkin_macros::include_proto;
 
 #[cfg(doctest)]
 mod external_doc_tests {
-    #![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/filters.md")]
+    #![doc = include_str!("../docs/src/filters/writing_custom_filters.md")]
+    #![doc = include_str!("../docs/src/filters/load_balancer.md")]
+    #![doc = include_str!("../docs/src/filters/local_rate_limit.md")]
+    #![doc = include_str!("../docs/src/filters/debug.md")]
+    #![doc = include_str!("../docs/src/filters/concatenate_bytes.md")]
+    #![doc = include_str!("../docs/src/filters/capture_bytes.md")]
+    #![doc = include_str!("../docs/src/filters/token_router.md")]
+    #![doc = include_str!("../docs/src/filters/compress.md")]
 }
-Original file line number
+Diff line change
@@ Expand Up / @@ -108,5 +108,5 @@ definitions: @@
             - address
     ```
-    [examples]: ../examples
+    [examples]: https://github.com/googleforgames/quilkin/blob/main/examples