diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 6e12211..b8c883c 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -1,120 +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/${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 }}