sphinx.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
#  https://raw.githubusercontent.com/coderefinery/sphinx-lesson-template/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"
  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:
    name: Build
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
      # https://github.com/marketplace/actions/checkout
      - 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.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: ${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
          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 (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

      # singlehtml
      - name: Generate singlehtml
        if: ${{ env.GENERATE_SINGLEHTML == 'true' }}
        run: |
          make singlehtml
          mv _build/singlehtml/ _build/dirhtml/singlehtml/

      # 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}

      # 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:
          rsync -a _build/dirhtml/ _gh-pages/

      # 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@v4
        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@v4
        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' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }}
        with:
          publish_branch: gh-pages
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: _gh-pages/
          force_orphan: true