merge coderefinery/sphinx-lesson-template

.github/workflows/sphinx.yml

@@ -1,44 +1,68 @@
-# 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]
 
 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"
-  # ^-- If these SPHINXOPTS are enabled, then be strict about the builds and fail on any warnings
+  GENERATE_PDF: true          # to enable, must be 'true' lowercase
+  GENERATE_SINGLEHTML: 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: write    
+      contents: read
+
     steps:
       # https://github.com/marketplace/actions/checkout
-      - uses: actions/checkout@v3
+      - 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@v4
         with:
-          python-version: 3.8
-          cache: "pip" # caching pip dependencies
+          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}"
+          echo "GENERATE_SINGLEHTML: ${GENERATE_SINGLEHTML}"
           set -x
           git rev-parse --abbrev-ref HEAD
           git branch
@@ -51,7 +75,8 @@ jobs:
 
       # 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
@@ -63,73 +88,80 @@ jobs:
           #   https://github.com/readthedocs/sphinx_rtd_theme/pull/1025
           sed -i 's/url_root="#"/url_root=""/' _build/dirhtml/index.html || true
 
+      # singlehtml
+      - name: Generate singlehtml
+        if: ${{ env.GENERATE_SINGLEHTML == 'true' }}
+        run: |
+          make singlehtml
+          mv _build/singlehtml/ _build/dirhtml/singlehtml/
 
-      # The following supports building all branches and combining on
-      # gh-pages
+      # 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/${PDF_FILENAME}
 
-      # 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 default branch, copy build to _gh-pages/ as the "main"
-      # deployment.
-      - name: Copy new build (default branch)
-        if: |
-          contains(github.event_name, 'push') &&
-          contains(github.ref, env.DEFAULT_BRANCH)
-        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 default branch, then copy the build to
-      # _gh-pages/branch/$brname (transforming '/' into '--')
-      - name: Copy new build (branch)
-        if: |
-          contains(github.event_name, 'push') &&
-          !contains(github.ref, env.DEFAULT_BRANCH)
-        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
-        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
+
+      # 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: |
           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/$defaultBranch' }}
+        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 }}