Feature/previews (#2234)

* Adjust base deployment, and get preview rolling?

* Slight DRY-ing.

* Fix description.

* Rework the local action dealio.

Misunderstood the structure, whoops.

* Add the shell bits...

* Add other permission necessary for the comment business.

.github/actions/build/action.yml

@@ -0,0 +1,17 @@
+---
+name: Build
+description: Setup to run and run mkdocs
+runs:
+  using: "composite"
+  steps:
+    - name: Setup build environment
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.x'
+        cache: 'pip'
+    - name: Install build requirements
+      shell: bash
+      run: pip install -r requirements.txt
+    - name: Build docs
+      shell: bash
+      run: mkdocs build

.github/workflows/docs-preview.yml

@@ -0,0 +1,27 @@
+---
+name: "Build docs preview"
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+concurrency: preview-${{ github.ref }}
+permissions:
+  # Needed to update the preview branch.
+  contents: write
+  # Needed to write/maintain the comment
+  pull-requests: write
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      - name: Build docs
+        uses: ./.github/actions/build
+      - name: Deploy docs preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: site

.github/workflows/docs.yml

@@ -4,7 +4,6 @@ on:
   push:
     branches:
       - main
-  workflow_dispatch:
 permissions:
   contents: write
 jobs:
@@ -13,12 +12,12 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v3
-      - name: Setup build environment
-        uses: actions/setup-python@v4
+      - name: Build docs
+        uses: ./.github/actions/build
+      - name: Deploy docs
+        uses: JamesIves/github-pages-deploy-action@v4
         with:
-          python-version: '3.x'
-          cache: 'pip'
-      - name: Install build requirements
-        run: pip install -r requirements.txt
-      - name: Build and deploy docs
-        run: mkdocs gh-deploy --force
+          folder: site
+          force: false
+          clean-exclude: |
+            pr-preview