Merge pull request #275 from coderefinery/rkdarst/gh-action

.github/workflows/sphinx: Update workflow to sphinx-lesson-template

.github/workflows/sphinx.yml

@@ -1,125 +1,158 @@
-# From: https://github.com/rkdarst/sphinx-actions-test/blob/master/.github/workflows/sphinx-build.yml
+# Deploy Sphinx.  This could be shorter, but we also do some extra
+# stuff.
+#
+# License: CC-0.  This is the canonical location of this file, which
+# you may want to link to anyway:
+#   https://github.com/coderefinery/sphinx-lesson-template/blob/main/.github/workflows/sphinx.yml
+
 
 name: sphinx
 on: [push, pull_request]
 
-# If these SPHINXOPTS are enabled, then be strict about the builds and
-# fail on any warnings
-#env:
-#  SPHINXOPTS: "-W --keep-going -T"
+env:
+  DEFAULT_BRANCH: "main"
+  # If these SPHINXOPTS are enabled, then be strict about the
+  # builds and fail on any warnings.
+  #SPHINXOPTS: "-W --keep-going -T"
+  GENERATE_PDF: true   # to enable, must be 'true' lowercase
+  PDF_FILENAME: lesson.pdf
+  MULTIBRANCH: true    # to enable, must be 'true' lowercase
 
 
 jobs:
-  build-and-deploy:
-    name: Build and gh-pages
+  build:
+    name: Build
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
     steps:
       # https://github.com/marketplace/actions/checkout
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
           lfs: true
+
       # https://github.com/marketplace/actions/setup-python
       # ^-- This gives info on matrix testing.
       - name: Install Python
-        uses: actions/setup-python@v2
-        with:
-          python-version: 3.8
-      # https://docs.github.com/en/actions/guides/building-and-testing-python#caching-dependencies
-      # ^-- How to set up caching for pip on Ubuntu
-      - name: Cache pip
-        uses: actions/cache@v2
+        uses: actions/setup-python@v4
         with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
-            ${{ runner.os }}-
+          python-version: '3.11'
+          cache: 'pip'
+
       # https://docs.github.com/en/actions/guides/building-and-testing-python#installing-dependencies
       # ^-- This gives info on installing dependencies with pip
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install -r requirements.txt
+
+        # Debug
       - name: Debugging information
+        env:
+          ref: ${{github.ref}}
+          event_name: ${{github.event_name}}
+          head_ref: ${{github.head_ref}}
+          base_ref: ${{github.base_ref}}
         run: |
-          echo "github.ref:" ${{github.ref}}
-          echo "github.event_name:" ${{github.event_name}}
-          echo "github.head_ref:" ${{github.head_ref}}
-          echo "github.base_ref:" ${{github.base_ref}}
+          echo "github.ref: ${ref}"
+          echo "github.event_name: ${event_name}"
+          echo "github.head_ref: ${head_ref}"
+          echo "github.base_ref: ${base_ref}"
+          echo "GENERATE_PDF: ${GENERATE_PDF}"
+          set -x
           git rev-parse --abbrev-ref HEAD
           git branch
           git branch -a
           git remote -v
+          python -V
+          pip list --not-required
+          pip list
+
 
       # Build
       - uses: ammaraskar/sphinx-problem-matcher@master
-      - name: Build Sphinx docs
+      - name: Build Sphinx docs (dirhtml)
+        # SPHINXOPTS used via environment variables
         run: |
           make dirhtml
+          # This fixes broken copy button icons, as explained in
+          #   https://github.com/coderefinery/sphinx-lesson/issues/50
+          #   https://github.com/executablebooks/sphinx-copybutton/issues/110
+          # This can be removed once these PRs are accepted (but the
+          # fixes also need to propagate to other themes):
+          #   https://github.com/sphinx-doc/sphinx/pull/8524
+          #   https://github.com/readthedocs/sphinx_rtd_theme/pull/1025
+          sed -i 's/url_root="#"/url_root=""/' _build/dirhtml/index.html || true
 
+      # PDF if requested
       - name: Generate PDF
+        if: ${{ env.GENERATE_PDF == 'true' }}
         run: |
           pip install https://github.com/rkdarst/sphinx_pyppeteer_builder/archive/refs/heads/main.zip
           make pyppeteer
-          mv _build/pyppeteer/*.pdf _build/dirhtml/_static/lesson.pdf
+          mv _build/pyppeteer/*.pdf _build/dirhtml/${PDF_FILENAME}
 
-      # The following supports building all branches and combining on
-      # gh-pages
-
-      # Clone and set up the old gh-pages branch
-      - name: Clone old gh-pages
+      # Stage all deployed assets in _gh-pages/ for simplicity, and to
+      # prepare to do a multi-branch deployment.
+      - name: Copy deployment data to _gh-pages/
         if: ${{ github.event_name == 'push' }}
-        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/
-      # If a push and main, copy build to _gh-pages/ as the "main"
-      # deployment.
-      - name: Copy new build (main)
-        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-        run: |
-          set -x
-          # Delete everything under _gh-pages/ that is from the
-          # primary branch deployment.  Eicludes the other branches
-          # _gh-pages/branch-* paths, and not including
-          # _gh-pages itself.
-          find _gh-pages/ -mindepth 1 ! -path '_gh-pages/branch*' -delete
+        run:
           rsync -a _build/dirhtml/ _gh-pages/
-      # If a push and not on main, then copy the build to
-      # _gh-pages/branch/$brname (transforming '/' into '--')
-      - name: Copy new build (branch)
-        if: ${{ github.event_name == 'push' && github.ref != 'refs/heads/main' }}
-        run: |
-          set -x
-          #brname=$(git rev-parse --abbrev-ref HEAD)
-          brname="${{github.ref}}"
-          brname="${brname##refs/heads/}"
-          brdir=${brname//\//--}   # replace '/' with '--'
-          rm -rf   _gh-pages/branch/${brdir}
-          rsync -a _build/dirhtml/ _gh-pages/branch/${brdir}
-      # Go through each branch in _gh-pages/branch/, if it's not a
-      # ref, then delete it.
-      - name: Delete old feature branches
+
+      # Use gh-pages-multibranch to multiplex different branches into
+      # one deployment. See
+      # https://github.com/coderefinery/gh-pages-multibranch
+      - name: gh-pages multibranch
+        uses: coderefinery/gh-pages-multibranch@main
+        if: ${{ github.event_name == 'push' && env.MULTIBRANCH == 'true' }}
+        with:
+          directory: _gh-pages/
+          default_branch: ${{ env.DEFAULT_BRANCH }}
+          publish_branch: gh-pages
+
+      # Add the .nojekyll file
+      - name: nojekyll
         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
+          touch _gh-pages/.nojekyll
+
+      # Save artifact for the next step.
+      - uses: actions/upload-artifact@master
+        if: ${{ github.event_name == 'push' }}
+        with:
+          name: gh-pages-build
+          path: _gh-pages/
+
+  # Deploy in a separate job so that write permissions are restricted
+  # to the minimum steps.
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    needs: build
+    # This if can't use the env context - find better way later.
+    if: ${{ github.event_name == 'push' }}
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/download-artifact@v3
+        if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }}
+        with:
+          name: gh-pages-build
+          path: _gh-pages/
+
+      # As of 2023, we could publish to pages via a Deployment.  This
+      # isn't done yet to give it time to stabilize (out of beta), and
+      # also having a gh-pages branch to check out is rather
+      # convenient.
 
       # Deploy
       # https://github.com/peaceiris/actions-gh-pages
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
-        if: ${{ github.event_name == 'push' }}
-        #if: ${{ success() && github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }}
         with:
           publish_branch: gh-pages
           github_token: ${{ secrets.GITHUB_TOKEN }}