Documentation update script (#474)

* First working version

* Testing

* Add docstrings, move to scripts directory

* Fix long line

* Update script to take the branch that docs are being built from rather than the doc directory

* Update workflow to use the script

* Use tighter match for maintenance branches

* Add changelog entry

* Better description

.github/workflows/build-docs.yml

@@ -1,9 +1,11 @@
-name: Update gh-pages documentation for main branch
+name: Update gh-pages documentation for main and maintenance branches
 
 on:
+  workflow_dispatch:
   push:
     branches:
-    - main
+      - main
+      - maint/[0-9]+.[0-9]+
 
 env:
   PYTHONUNBUFFERED: 1
@@ -27,21 +29,10 @@ jobs:
       run: |
         python -m pip install --upgrade pip setuptools wheel
         python -m pip install .[docs]
-    - name: Build HTML documentation with Sphinx
-      run: |
-        cd docs
-        python -m sphinx -b html -d doctrees source build
     - name: Configure Git
       run: |
         git config user.name "Documentation Bot"
         git config user.email "<>"
-    - name: Update gh-pages branch
+    - name: Build documentation and deploy to gh-pages
       run: |
-        git fetch --depth=1 origin gh-pages
-        git checkout gh-pages
-        rm -r dev
-        mv docs/build dev
-        git add dev
-        # Only commit if there are changes
-        git diff-index --quiet --cached HEAD || git commit -m "Automated update of main branch documentation"
-        git push origin gh-pages
+        python scripts/update_docs.py --token ${{ secrets.GITHUB_TOKEN }} ${{ env.GITHUB_REF }}

docs/source/changes.rst

@@ -21,6 +21,9 @@ Continuous integration and build
 
 * Add cron-job-based workflow to validate installation of the latest
   wheel and sdist from PyPI. (#465)
+* Add new script for automating gh-pages updates, and extend automated
+  documentation building to the maintenance branches in addition to
+  the main branch. (#474)
 
 
 Release 0.3.1