ci: rework docs workflows

.github/workflows/docs-release.yml

@@ -0,0 +1,71 @@
+name: Release Docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - gh-pages
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+concurrency:
+  group: Release Docs
+  cancel-in-progress: true
+
+jobs:
+  deploy_docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: get gh-pages
+        uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+
+      - uses: ./.github/actions/prepare
+
+      - name: Craete a pages artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./docs/generated
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2
+
+      - name: Store Coverage Badge
+        run: cp ./docs/generated/stable/coverage.svg /tmp/coverage.svg
+
+      - name: get gh-pages
+        uses: actions/checkout@v3
+        with:
+          ref: main
+
+      - name: Update Coverage Badge
+        run: cp /tmp/coverage.svg ./docs/coverage.svg
+
+      - id: coverage_changed
+        run: echo "coverage_changed=$(git status --porcelain -u | grep -c docs/coverage.svg)" >> "$GITHUB_OUTPUT"
+
+      - id: push_coverage
+        env:
+          COVERAGE_CHANGED: ${{ steps.coverage_changed.outputs.coverage_changed }}
+        run: echo "push_coverage=$(if [[ "$COVERAGE_CHANGED" != '0' ]] ; then echo '1' ; else echo '0' ; fi)" >> "$GITHUB_OUTPUT"
+
+      - if: steps.push_coverage.outputs.push_coverage != '0'
+        uses: ./.github/actions/unprotect-main
+        with:
+          ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
+
+      - if: steps.push_coverage.outputs.push_coverage != '0'
+        run: |
+          git add docs/coverage.svg
+          git commit -m "docs: update documentation coverage badge"
+          git push
+
+      - if: ${{ always() && steps.push_coverage.outputs.push_coverage != '0' }}
+        uses: ./.github/actions/protect-main
+        with:
+          ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}

.github/workflows/docs-update.yml

@@ -0,0 +1,70 @@
+name: Update Docs
+
+on:
+  push:
+    tags:
+      # https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string -- github doesn't like this regex??
+      - v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)
+      - v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-|\+)([a-zA-Z0-9]|-|+|\.)*
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: Update Docs
+  cancel-in-progress: false
+
+jobs:
+  update_docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout the docs
+        uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+
+      - name: Save old docs
+        run: tar -cvf /tmp/old-docs.tar ./docs/generated
+
+      - name: Checkout tag
+        uses: actions/checkout@v3
+        with:
+          ref: ${{ github.ref_name }}
+          clean: false #  doesn't seem to work?? Hense use of tar.
+
+      - uses: ./.github/actions/prepare
+
+      - name: Restore old docs
+        run: |
+          mkdir -p ./docs/generated
+          tar -xf /tmp/old-docs.tar ./docs/generated -C ./docs/generated
+
+      - name: Build docs
+        run: pnpm run docs
+
+      - name: Save new docs
+        run: tar -cvf /tmp/new-docs.tar ./docs/generated
+
+      - name: checkout the docs
+        uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+          clean: false #  doesn't seem to work?? Hense use of tar.
+
+      - uses: ./.github/actions/prepare
+
+      - name: Restore new docs
+        run: |
+          mkdir -p ./docs/generated
+          tar -xf /tmp/new-docs.tar ./docs/generated -C ./docs/generated
+
+      - name: Commit
+        run: |
+          git add -f docs/generated
+          git commit -m "docs: update documentation"
+          git push
+        continue-on-error: true

.github/workflows/release.yml

@@ -32,20 +32,3 @@ jobs:
         uses: ./.github/actions/protect-main
         with:
           ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
-
-  release_docs:
-    if: needs.release.outputs.did_release != '0'
-    needs: release
-    uses: ./.github/workflows/release-docs.yml
-name: Release
-
-on:
-  push:
-    branches:
-      - main
-
-permissions:
-  contents: write
-  id-token: write
-
-  pages: write