feat(ci): Docs workflow and reusable CI actions

.github/actions/mike-docs/action.yaml

@@ -0,0 +1,35 @@
+name: Documentation
+description: Build and publish documentation using mike
+inputs:
+  version:
+    description: Version number
+    required: true
+  alias:
+    description: Alias name
+  push:
+    description: Whether to push the built documentation to the repository
+    required: true
+    default: "false"
+  pre_release:
+    description: Whether this version is a pre-release version (to render a notification banner)
+    default: "false"
+runs:
+  using: "composite"
+  steps:
+    - run: |
+        # https://github.com/jimporter/mike#deploying-via-ci
+        git fetch origin gh-pages --depth=1
+
+        # For proper UI integration: https://github.com/actions/checkout/pull/1184
+        git config user.name "github-actions[bot]"
+        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      shell: bash
+    - env:
+        DOCS_PRERELEASE: ${{ inputs.pre_release }}
+      run: |
+        MIKE_OPTIONS=( "--update-aliases" )
+        if [ "true" = "${{ inputs.push }}" ]; then
+          MIKE_OPTIONS+=( "--push" )
+        fi
+        mike deploy ${{ inputs.version }} ${{ inputs.alias }} "${MIKE_OPTIONS[@]}"
+      shell: bash

.github/actions/python-deps/action.yaml

@@ -0,0 +1,18 @@
+name: Install Python dependencies
+description: Install all core and optional Python dependencies
+inputs:
+  pythonVersion:
+    description: Python version to set up (see actions/setup-python@v5)
+    required: true
+runs:
+  using: "composite"
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.pythonVersion }}
+    - name: Install Python dependencies
+      run: |
+        uv pip install --system -r requirements-dev.txt
+        uv pip install --system --no-deps .
+      shell: bash

.github/workflows/docs.yaml

@@ -0,0 +1,47 @@
+name: Build and optionally deploy documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python and dependencies
+        uses: ./.github/actions/python-deps
+        with:
+          pythonVersion: 3.11
+      - name: Build documentation
+        run: mkdocs build
+      - name: Archive built documentation
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: public/docs
+  deploy-docs:
+    runs-on: ubuntu-latest
+    name: Deploy documentation to GitHub Pages
+    # publish on 'main' only to prevent version clutter
+    if: ${{ github.ref == 'refs/heads/main' }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python and dependencies
+        uses: ./.github/actions/python-deps
+        with:
+          pythonVersion: 3.11
+      - name: Restore built docs from artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: backend_docker
+          path: public/docs
+      - name: Publish documentation
+        uses: ./.github/actions/mike-docs
+        with:
+          version: ${{ github.event.release.tag_name }}
+          alias: latest

.github/workflows/test-and-lint.yaml

@@ -20,16 +20,10 @@ jobs:
       PRE_COMMIT_HOME: "${{ github.workspace }}/.cache/pre-commit"
     steps:
       - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
       - name: Set up Python and dependencies
-        uses: actions/setup-python@v5
+        uses: ./.github/actions/python-deps
         with:
-          python-version: 3.11
-      - name: Install dependencies
-        run: |
-          pip install -U uv
-          uv pip install --no-deps . -r requirements-dev.txt
+          pythonVersion: 3.11
       - name: Cache pre-commit tools
         uses: actions/cache@v4
         with:
@@ -50,12 +44,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Set up oldest supported Python on ${{ matrix.os }}
-        uses: actions/setup-python@v5
+        uses: ./.github/actions/python-deps
         with:
-          python-version: "3.10"
-      - name: Run tests on oldest supported Python
+          pythonVersion: 3.10
+      - name: Execute python tests
         run: |
-          pip install -U uv
-          uv pip install -r requirements-dev.txt
           uv pip install .  # need to install without --no-deps to work around non-portable dependency resolution in `uv pip compile`
           pytest