fix: skip docs build/publish on pull_request, not just push

The sphinx job unconditionally ran (and tried to publish to gh-pages)
on every PR, including ones whose branch lives in a fork -- even the
author's own fork (e.g. #198). GitHub Actions always issues a
read-only GITHUB_TOKEN for pull_request-triggered runs when the head
repo differs from the base repo, so the gh-pages push step there fails
by design, regardless of repo/workflow permission settings.

There was already a commented-out attempt at this exact guard inside
sphinx.yml itself (`if: github.event_name != 'pull_request'`), but it
could never have worked there: sphinx.yml is invoked via
`workflow_call`, and github.event_name inside a called workflow is
always "workflow_call", never the original triggering event. Moving
the condition to the caller job in master.yml (which does see the real
triggering event) is what actually works -- removed the dead comment
from sphinx.yml accordingly.

This also means PR runs no longer spend ~10+ minutes building docs
that were never going anywhere, and unreviewed PR content never
reaches the live public docs site.

Author: petercorke

.github/workflows/master.yml

@@ -77,6 +77,12 @@ jobs:
         file: ./coverage.xml
   sphinx:
     # If the above worked:
-    # Build docs and upload to GH Pages
+    # Build docs and upload to GH Pages -- only on push (merge to master/future),
+    # never on pull_request: a PR whose branch lives in a fork (including the
+    # author's own fork) gets a read-only GITHUB_TOKEN by GitHub's own design,
+    # so the gh-pages push step always fails there regardless of repo settings.
+    # Publishing unreviewed PR content to the live docs site isn't desired
+    # either way.
     needs: unittest
+    if: ${{ github.event_name != 'pull_request' }}
     uses: ./.github/workflows/sphinx.yml

.github/workflows/sphinx.yml

@@ -6,7 +6,6 @@ on:
 jobs:
   sphinx:
     runs-on: ubuntu-22.04
-    # if: ${{ github.event_name != 'pull_request' }}
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python 3.12