ci/docs: Run on tagged releases only (#1009)

This changes the ci/docs workflow
to only run on tagged releases by default
instead of every push to main.

This also updates the existing workflow_dispatch trigger to expect an
input specifying the ref to publish docs from. With that, you should be
able to specify a branch or tag from the Actions UI.
Example of how this looks from [one of my
projects](https://github.com/abhinav/restack/blob/89e6749811ee0cccc4cc8884757ca8d291d73272/.github/workflows/release.yml):

![image](https://user-images.githubusercontent.com/41730/210201985-a5557627-c6e6-4c4c-a773-7fea3a105dce.png)


Going this route has the disadvantage that
all documentation fixes and updates after a release will not be
available on the website until another release or a manual publish which
can accidentally also publish documentation for unreleased features.

Refs #1008

.github/workflows/docs.yml

@@ -2,11 +2,20 @@ name: GitHub Pages
 
 on:
   push:
-    branches: [master]
+    tags: ['v*']
 
   # This lets us publish the workflow
   # manually from the GitHub Actions UI.
+  #
+  # It expects a single input:
+  # the Git ref we want to build and publish the docs for.
   workflow_dispatch:
+    inputs:
+      head:
+        description: "Git commitish to check out."
+        required: true
+        type: string
+
 
 # Run at most one publish job at a time,
 # cancelling others if a new one starts.
@@ -19,8 +28,18 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - name: Checkout
+      # We have two checkout steps running based on
+      # whether the workflow was manually trigerred.
+      # If manually trigerred, we use the provided ref,
+      # otherwise we use the default ref.
+      - name: Checkout (on release)
+        if:  github.event_name != 'workflow_dispatch'
+        uses: actions/checkout@v3
+      - name: Checkout (manual)
+        if:  github.event_name == 'workflow_dispatch'
         uses: actions/checkout@v3
+        with:
+          ref: ${{ inputs.head }}
 
       - name: Set up Node
         uses: actions/setup-node@v3