Add CI and GitHub pages rendering.

Co-authored-by: Nathan Wilcox <[email protected]>
Signed-off-by: Daira-Emma Hopwood <[email protected]>

.github/workflows/merge-acceptance.yaml

@@ -0,0 +1,18 @@
+name: 'Check Rendering'
+on: pull_request
+jobs:
+  check-render:
+    runs-on: 'ubuntu-latest'
+    steps:
+    - name: Rust Toolchain Version Diagnostics
+      run: cargo --version --verbose && rustup --version
+    - uses: taiki-e/cache-cargo-install-action@v1
+      with:
+        tool: [email protected]
+    - uses: taiki-e/cache-cargo-install-action@v1
+      with:
+        tool: [email protected]
+    - uses: actions/checkout@v3
+    - run: mdbook build
+    - name: Check for Orphaned Files
+      run: ./util/find-orphaned-files.sh

.github/workflows/render-site.yaml

@@ -0,0 +1,64 @@
+# Reference: https://nathan-at-least.github.io/auto-deploy-howto.html
+name: Deploy Rendered Site
+
+on:
+  push:
+    branches: [ main ]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  render-and-deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    # These initial steps set up the toolchain:
+    - name: Rust Toolchain Version Diagnostics
+      run: cargo --version --verbose && rustup --version
+      with:
+        tool: [email protected]
+    - uses: taiki-e/cache-cargo-install-action@v1
+      with:
+        tool: [email protected]
+
+    # Now get the user content:
+    - uses: actions/checkout@v3
+
+    # Now render to the site:
+
+    # Each deploy overwrites the contents of `gh-pages` branch from
+    # `main`, but also introduces a merge structure so that the history of
+    # `gh-pages` is tracked:
+    - name: Overwrite gh-pages branch with main branch
+      run: |
+        set -x
+        BASE_BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+        git config --global user.name 'autodeploy'
+        git config --global user.email 'autodeploy'
+        git fetch
+        git checkout gh-pages # ensure we have local branch
+        git checkout "$BASE_BRANCH"
+        TMP='local-temp-branch'
+        git checkout -b "$TMP" # Same tree state as main branch
+        git merge \
+          --strategy ours \
+          --commit \
+          -m 'Auto-deploy: overwriting with `main` branch' \
+          --allow-unrelated-histories \
+          gh-pages
+        git checkout gh-pages
+        git merge --ff-only "$TMP"
+        git branch -d "$TMP"
+    - run: mdbook build
+    - name: Rendered manifest
+      run: find ./docs -type f -exec ls -ld '{}' \;
+    - name: Disable jekyll
+      run: touch .nojekyll
+    - name: Commit and Push render to gh-pages
+      run: |
+        set -x
+        git add --all
+        git commit -m 'Auto-deploy: rendered output'
+        git push

util/find-orphaned-files.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+#
+# Print out any md files within `./src` which aren't linked from SUMMARY.
+#
+# If there are any, exit with non-zero status
+
+set -efuo pipefail
+
+function main
+{
+  # Move to src dir regardless of `pwd`:
+  cd "$(dirname "$(readlink -f "$0")")/../src"
+
+  local DATADIR="$(mktemp --directory)"
+  local LINKED="${DATADIR}/linked"
+  local ACTUAL="${DATADIR}/actual"
+  local DIFF="${DATADIR}/diff"
+
+  parse-linked-files < './SUMMARY.md' > "$LINKED"
+  find-actual-files > "$ACTUAL"
+
+  set +o pipefail # It's ok for this pipeline to fail:
+  diff -u "$LINKED" "$ACTUAL" | grep -Eve '^(\+\+\+|---)' | grep '^[+-]' | tee "$DIFF"
+
+  if [ "$(wc -l < "$DIFF")" -eq 0 ]
+  then exit 0
+  else exit 1
+  fi
+}
+
+function parse-linked-files
+{
+  grep '(' | sed 's/^.*(//; s/)$//' | grep -v '^$' | sort
+}
+
+function find-actual-files
+{
+  find . -type f -not -name 'SUMMARY.md' -name '*.md' | sort
+}
+
+main "$@"