From 54dea8b330b117a961848350b639bbaa281383f7 Mon Sep 17 00:00:00 2001
From: Daira-Emma Hopwood <daira@jacaranda.org>
Date: Mon, 18 Mar 2024 10:58:28 +0000
Subject: [PATCH] Add CI and GitHub pages rendering.

Co-authored-by: Nathan Wilcox <nathan-at-least@users.noreply.github.com>
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
---
 .github/workflows/merge-acceptance.yaml | 18 +++++++
 .github/workflows/render-site.yaml      | 64 +++++++++++++++++++++++++
 util/find-orphaned-files.sh             | 41 ++++++++++++++++
 3 files changed, 123 insertions(+)
 create mode 100644 .github/workflows/merge-acceptance.yaml
 create mode 100644 .github/workflows/render-site.yaml
 create mode 100755 util/find-orphaned-files.sh

diff --git a/.github/workflows/merge-acceptance.yaml b/.github/workflows/merge-acceptance.yaml
new file mode 100644
index 0000000..7ac08bb
--- /dev/null
+++ b/.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: mdbook@0.4.37
+    - uses: taiki-e/cache-cargo-install-action@v1
+      with:
+        tool: mdbook-katex@0.6.0
+    - uses: actions/checkout@v3
+    - run: mdbook build
+    - name: Check for Orphaned Files
+      run: ./util/find-orphaned-files.sh
diff --git a/.github/workflows/render-site.yaml b/.github/workflows/render-site.yaml
new file mode 100644
index 0000000..4750555
--- /dev/null
+++ b/.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: mdbook@0.4.37
+    - uses: taiki-e/cache-cargo-install-action@v1
+      with:
+        tool: mdbook-katex@0.6.0
+
+    # 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
diff --git a/util/find-orphaned-files.sh b/util/find-orphaned-files.sh
new file mode 100755
index 0000000..526a7d0
--- /dev/null
+++ b/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 "$@"