chore: Simplify publish_docs workflow (#749)

(note: this is a re-submit of #747 to resolve CI issues.)

from [janbrasna](https://github.com/janbrasna)

The current docs build takes several minutes, the toolchain setup
doesn't really do anything, and the workflow is triggered from
unexpected events (probably not doing what it was believed to do) — so
this is an attempt to simplify, and speed up. The main issues are:

    the curl doesn't run due to -y error; OTOH neither rustup nor cargo
needs any manual setting up here…
    the on:check_run doesn't imply successful build, but more
importantly triggers also outside of master/PRs basically on any branch
anywhere commit checks are run, publishing docs on pretty much any push
to any ref unnecessarily.
    something in the build of validator_derive (either validator, grpcio
or google-cloud-rust-raw) takes ~6-7mins to build, basically 99% of the
whole workflow run, so question is whether to switch to binaries or
caching?
    The used Node 16 actions raise deprecation warnings, need updating.

Logs:

    before: runs/10327553562 (triggered from RRM181 PR check that hasn't
landed yet)
    after: job/28971156482#step:6:1
    after cache: job/28972053092#step:6:1

More detailed explainers are in [the
changeset](#747).

.github/workflows/publish_docs.yml

@@ -1,57 +1,37 @@
 name: Publish docs to pages
 run-name: ${{ github.actor }} is publishing docs
 on:
-    # on a successful push
+    workflow_dispatch:  # Allow manual triggering
     push:
-        # only run on pushes to these branches
-        branches:
-            - 'master'
-            - 'main'
-            - 'docs'
-        # or run if pushes to these files.
-        # paths:
-        #    - 'docs/**.md'
-    check_run:
-        types:
-            # Only run if we have a successfully completed branch
-            - completed
-    # if desired, we can also use cron like rules to trigger these
-    # schedule:
-        #   - cron: 0 0 * * *
-    # Allow for manual triggering
-    workflow_dispatch:
+        branches: [master,main]
+        # paths: ['docs/**.md']  # API docs need building always
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-permissions:
-    contents: read
-    pages: write
-    id-token: write
-
-# Allow only one concurrent deployment. Cancel any in-progress.
 concurrency:
-    group: "pages"
-    cancel-in-progress: true
+    group: github-pages
+    cancel-in-progress: false  # Skip any intermediate builds but finish deploying
 
 jobs:
     build:
         runs-on: ubuntu-latest
         env:
-            MDBOOK_ENV: 0.4.24
-            MERMAID_ENV: 0.12.6
+            MDBOOK_ENV: 0.4.40
+            MERMAID_ENV: 0.13.0
             DEST_DIR: /home/runner/.cargo/bin
         steps:
-            # these are other job descriptions to call.
-            - uses: actions/checkout@v3
-            - name: Configure rust  # TODO: can we export building rust and installing mdbook as an artifact and reuse it?
-              run: |
-                curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
-                rustup update
-                export PATH=$PATH:$DEST_DIR
+            - uses: actions/checkout@v4
+            - uses: actions/cache@v4
+              with:
+                path: |
+                  ~/.cargo/bin/
+                  ~/.cargo/registry/
+                  ~/.cargo/git/
+                  target/
+                key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
             - name: Install mdBook
               run: |
+                export PATH=$PATH:$DEST_DIR
                 curl -sSL "https://github.com/rust-lang/mdBook/releases/download/v$MDBOOK_ENV/mdbook-v$MDBOOK_ENV-x86_64-unknown-linux-gnu.tar.gz" | tar -xz --directory $DEST_DIR
                 curl -sSL "https://github.com/badboy/mdBook-mermaid/releases/download/v$MERMAID_ENV/mdbook-mermaid-v$MERMAID_ENV-x86_64-unknown-linux-gnu.tar.gz" | tar -xz --directory $DEST_DIR
-            # actually build the book
             - name: Build the main book
               run: cd docs && mdbook build
             - name: Build API docs
@@ -60,11 +40,10 @@ jobs:
             - name: Copy cargo docs to API dir
               run: mkdir -p docs/output/api && cp -r target/doc/* docs/output/api
             - name: Upload artifact
-              uses: actions/upload-pages-artifact@v1
+              uses: actions/upload-pages-artifact@v3
               with:
                 path: ./docs/output
 
-    # write the pages
     deploy:
         needs: build
         permissions:
@@ -75,6 +54,6 @@ jobs:
             url: ${{ steps.deployment.outputs.page_url }}
         runs-on: ubuntu-latest
         steps:
-            - name: Deploy to Github Pages
+            - name: Deploy to GitHub Pages
               id: depolyment
-              uses: actions/deploy-pages@v2
+              uses: actions/deploy-pages@v4