diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 976bb1d..c69eada 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -1,4 +1,10 @@ -# 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] @@ -6,49 +12,49 @@ on: [push, pull_request] env: DEFAULT_BRANCH: "main" #SPHINXOPTS: "-W --keep-going -T" - # ^-- If these SPHINXOPTS are enabled, then be strict about the builds and fail on any warnings + # ^-- 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 + MULTIBRANCH: true # same + 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@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 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 "GENERATE_PDF:" ${{env.GENERATE_PDF}} set -x git rev-parse --abbrev-ref HEAD git branch @@ -62,6 +68,7 @@ jobs: # Build - uses: ammaraskar/sphinx-problem-matcher@master - name: Build Sphinx docs + # SPHINXOPTS used via environment variables run: | make dirhtml # This fixes broken copy button icons, as explained in @@ -73,60 +80,29 @@ jobs: # https://github.com/readthedocs/sphinx_rtd_theme/pull/1025 sed -i 's/url_root="#"/url_root=""/' _build/dirhtml/index.html || true + # PDF + - 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 - # 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 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 + + # Clone and set up the old gh-pages branch + - 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 @@ -134,12 +110,38 @@ jobs: run: | touch _gh-pages/.nojekyll + # Save artifact + - uses: actions/upload-artifact@master + 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 + permissions: + contents: write + + steps: + - uses: actions/download-artifact@v3 + 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: ${{ success() && github.event_name == 'push' && github.ref == 'refs/heads/$DEFAULT_BRANCH' }} with: publish_branch: gh-pages github_token: ${{ secrets.GITHUB_TOKEN }}