ci: deploy docs to gh-pages on tagged releases

Trigger the Docs workflow on version tags (v*) and add a deploy job
that publishes the built Sphinx HTML to the gh-pages branch using
peaceiris/actions-gh-pages. PRs and branch pushes still build (and
now upload an artifact) but do not deploy.

.github/workflows/docs.yml

@@ -1,16 +1,21 @@
 name: Docs
 
-on: [push, pull_request]
+on:
+  push:
+    branches: [master, main]
+    tags:
+      - 'v*'
+  pull_request:
 
 jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python 3.8
-      uses: actions/setup-python@v4
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
       with:
-        python-version: 3.8
+        python-version: '3.12'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
@@ -22,3 +27,39 @@ jobs:
     - name: Build documentation
       run: |
         sphinx-build docs build/html
+    - name: Upload documentation artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: html-docs
+        path: build/html
+
+  deploy:
+    needs: docs
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+    - name: Build pycapnp and install
+      run: |
+        python setup.py build
+        pip install .
+    - name: Build documentation
+      run: |
+        sphinx-build docs build/html
+        touch build/html/.nojekyll
+    - name: Deploy to gh-pages
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./build/html
+        publish_branch: gh-pages