sphinx.yml: simplified and harmonized with sphinx.yml as in dictIO repo

.github/workflows/sphinx.yml

@@ -1,53 +1,31 @@
-# From: https://github.com/coderefinery/sphinx-lesson/blob/master/.github/workflows/sphinx.yml
+name: Build and publish documentation
+run-name: Build and publish documentation (${{github.event.ref}} by @${{ github.actor }})
 
-name: Build and publish Sphinx documentation on GitHub Pages
 on: push
 
 env:
   DEFAULT_BRANCH: 'release'
-  #SPHINXOPTS: "-W --keep-going -T"
+  #SPHINXOPTS: '-W --keep-going -T'
   # ^-- If these SPHINXOPTS are enabled, then be strict about the builds and fail on any warnings
 
 jobs:
   build-and-publish-docs:
-    name: Build and publish Sphinx documentation on GitHub Pages
+    name: Build and publish documentation
     runs-on: ubuntu-latest
     steps:
-      # PREPARE
-
-      # Checkout active branch (the branch that triggered the workflow)
-      # https://github.com/marketplace/actions/checkout
       - name: Checkout active branch
         uses: actions/checkout@v3
         with:
           fetch-depth: 1
           lfs: true
-
-      # Install Python
-      # https://github.com/marketplace/actions/setup-python
       - name: Install Python
         uses: actions/setup-python@v4
         with:
           python-version: '3.10'
-
-      # Cache pip
-      # https://docs.github.com/en/actions/guides/building-and-testing-python#caching-dependencies
-      - name: Cache pip
-        uses: actions/cache@v3
-        with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
-            ${{ runner.os }}-
-
-      # Install dependencies
-      # https://docs.github.com/en/actions/guides/building-and-testing-python#installing-dependencies
+          cache: 'pip' # cache pip dependencies
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements-dev.txt
-      - name: Debugging information
+        run: pip install -r requirements-dev.txt
+      - name: Print debugging information
         run: |
           echo "github.ref:" ${{github.ref}}
           echo "github.event_name:" ${{github.event_name}}
@@ -62,28 +40,37 @@ jobs:
           pip list --not-required
           pip list
 
-      # BUILD DOCUMENTATION
-
       # Build documentation
       - uses: ammaraskar/sphinx-problem-matcher@master
-      - name: Build Sphinx docs
+      - name: Build documentation
         run: |
           cd docs
           make html
 
-      # COPY DOCUMENTATION to gh-pages branch
-
-      # Clone and cleanup gh-pages branch
-      - name: Clone gh-pages branch
+      - name: Clone and cleanup gh-pages branch
         run: |
           set -x
           git fetch
           ( git branch gh-pages remotes/origin/gh-pages && git clone . --branch=gh-pages _gh-pages/ ) || mkdir _gh-pages
           rm -rf _gh-pages/.git/
           mkdir -p _gh-pages/branch/
 
-      # Copy documentation to _gh-pages/  (if push happened on default branch)
-      - name: Copy documentation (default branch)
+      # Delete orphaned branch-folders:
+      # Go through each subfolder in _gh-pages/branch/
+      # If it relates to an orphaned branch, delete it.
+      - name: Delete orphaned branch-folders
+        run: |
+          set -x
+          for brdir in `ls _gh-pages/branch/` ; do
+              brname=${brdir//--/\/}   # replace '--' with '/'
+              if ! git show-ref remotes/origin/$brname ; then
+                  echo "Removing $brdir"
+                  rm -r _gh-pages/branch/$brdir/
+              fi
+          done
+
+      # Copy documentation to _gh-pages/  (if push happened on release branch)
+      - name: Copy documentation to _gh-pages/
         if: |
           contains(github.ref, env.DEFAULT_BRANCH)
         run: |
@@ -95,9 +82,9 @@ jobs:
           find _gh-pages/ -mindepth 1 ! -path '_gh-pages/branch*' -delete
           rsync -a docs/build/html/ _gh-pages/
 
-      # Copy documentation to _gh-pages/branch/$brname  (if push happened on another, non-default branch)
+      # Copy documentation to _gh-pages/branch/$brname  (if push happened on any other branch)
       # ('/' gets replaced by '--')
-      - name: Copy documentation (non-default branch)
+      - name: Copy documentation to _gh-pages/branch/${{github.ref}}
         if: |
           !contains(github.ref, env.DEFAULT_BRANCH)
         run: |
@@ -109,30 +96,12 @@ jobs:
           rm -rf   _gh-pages/branch/${brdir}
           rsync -a docs/build/html/ _gh-pages/branch/${brdir}
 
-      # Delete orphaned branch-folders
-      # Go through each subfolder in _gh-pages/branch/. If it is not a ref, delete it.
-      - name: Delete orphaned branch-folders
-        if: ${{ github.event_name == 'push' }}
-        run: |
-          set -x
-          for brdir in `ls _gh-pages/branch/` ; do
-              brname=${brdir//--/\/}   # replace '--' with '/'
-              if ! git show-ref remotes/origin/$brname ; then
-                  echo "Removing $brdir"
-                  rm -r _gh-pages/branch/$brdir/
-              fi
-          done
-
       # Add .nojekyll file
-      - name: nojekyll
-        run: |
-          touch _gh-pages/.nojekyll
-
-      # PUBLISH DOCUMENTATION
+      - name: Add .nojekyll file
+        run: touch _gh-pages/.nojekyll
 
-      # Commit gh-pages branch and publish it on GitHub Pages
-      # https://github.com/peaceiris/actions-gh-pages
-      - name: Publish
+      # Publish: Commit gh-pages branch and publish it to GitHub Pages
+      - name: Publish documentation
         uses: peaceiris/actions-gh-pages@v3
         with:
           publish_branch: gh-pages