template/.github/workflows/deploy-book-ghpages.yml

name: deploy-book

# Based on:
# https://jupyterbook.org/en/stable/publish/gh-pages.html

# NOTE to template users:
# You should not need to edit this file. This is not the workflow file that is being run on every push.
# Instead, on every push workflow `call-deploy-book` calls the `deploy-book` workflow at the original template repository:
# https://github.com/TeachBooks/template

on:
  workflow_call:

# Inherit configuration variables in the environment, or assign default values.
# Configuration variables may be set as explained here:
# https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository
env:
  # `main` as primary by default, advised to make it `published` to start using draft-publish-workflow
  PRIMARY_BRANCH: ${{ vars.PRIMARY_BRANCH != '' && vars.PRIMARY_BRANCH || 'main' }}
  # Space-separated list of alias-rules, e.g. 'draft:main alias:really-long-branch-name'
  # By default, `draft` links to `main`. Advised to link `book` to `publish`
  # If no aliases are wanted, BRANCH_ALIASES may be set to ' ' (space).
  BRANCH_ALIASES: ${{ vars.BRANCH_ALIASES != '' && vars.BRANCH_ALIASES || 'draft:main' }}
  # Space-separated list of branch names, e.g. 'main second third'.
  # By default, deploy all branches. This is indicated by '*'.
  BRANCHES_TO_DEPLOY: ${{ vars.BRANCHES_TO_DEPLOY != '' && vars.BRANCHES_TO_DEPLOY || '*' }}

jobs:
  get-branches:
    runs-on: ubuntu-latest
    outputs:
      branches: ${{ steps.set-branches.outputs.branches }}
    permissions:
      contents: read
    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0

    - id: set-branches
      name: Set branches
      run: |
        if [ "$BRANCHES_TO_DEPLOY" == '*' ]; then
          branches=$(git branch -r | sed 's,\s*origin/,,g')
        else
          branches=$(echo "$BRANCHES_TO_DEPLOY" | tr ' ' '\n' | grep -E '\S')
        fi
        echo "$branches" > raw.txt
        echo "$branches" | tr '/":<>|*?\/\\' '-' > clean.txt
        paste -d ' ' raw.txt clean.txt | sed 's/ / -> /g'
        branches=$(echo "$branches" | jq -Rn '[inputs]')
        echo "branches=$(echo $branches)" >> $GITHUB_OUTPUT

  build-books:
    runs-on: ubuntu-latest
    needs: get-branches
    if: ${{ needs.get-branches.outputs.branches != '[]' }}
    permissions:
      pages: write
      id-token: write
    strategy:
      # If one branch fails, we may still want to deploy the other
      fail-fast: false
      matrix:
        branch: ${{ fromJson(needs.get-branches.outputs.branches) }}
    steps:
    - name: Checkout to branch
      uses: actions/checkout@v4
      with:
        ref: ${{ matrix.branch }}

    - name: Cache page build
      id: cache-html
      uses: actions/cache@v4
      with:
        path: "book/_build/html"
        key: html-build-${{ hashFiles('book/**', 'figures/**', 'requirements.txt') }}

    - if: ${{ steps.cache-html.outputs.cache-hit != 'true' }}
      name: Set up Python 3.11
      uses: actions/setup-python@v5
      with:
        python-version: 3.11
        cache: 'pip'

    - if: ${{ steps.cache-html.outputs.cache-hit != 'true' }}
      name: Install dependencies
      run: |
        pip install -r requirements.txt

    - if: ${{ steps.cache-html.outputs.cache-hit != 'true' }}
      name: Preprocess & build the book from branch
      run: |
        echo $PATH
        if [ ${{matrix.branch}} == $PRIMARY_BRANCH ]; then
          teachbooks build --publish book/
        else
          teachbooks build book/
        fi


    - name: Clean branch name of disallowed characters
      run: |
        echo "MATRIX_BRANCH_NAME_CLEAN=$(echo ${{ matrix.branch }} | tr '/":<>|*?\/\\' '-')" >> $GITHUB_ENV

    - name: Upload the built book HTML as an artifact
      uses: actions/upload-artifact@v4
      with:
        name: ${{ env.MATRIX_BRANCH_NAME_CLEAN }}
        path: "book/_build/html"

  deploy-books:
    # Run after build-books, even if it failed
    if: always()
    needs: build-books
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    steps:
    - uses: actions/checkout@v4

    - run: |
        mkdir final/

    - name: Download all book artifacts
      uses: actions/download-artifact@v4
      with:
        path: "final/"

    - name: Copy primary book to root, fail if names conflict
      timeout-minutes: 1
      run: |
        GLOBIGNORE=".:.."
        # -i leads to a prompt in case of conflict, => a timeout
        if [ -d final/"$PRIMARY_BRANCH" ]; then
          cp -irv final/"$PRIMARY_BRANCH"/* final/
        fi
        ls -a final/

    - name: Symlink branch aliases
      run: |
        echo "$BRANCH_ALIASES" | tr ' ' '\n' | grep -E '\S' |
        while IFS=':' read -r key value; do
          # If the target branch is to be deployed, make symlink to it.
          if [ "$BRANCHES_TO_DEPLOY" == "*" ] || echo "$BRANCHES_TO_DEPLOY" | tr ' ' '\n' | grep "^$value$"; then
            # Clean branch names of special characters
            clean_key=$(echo "$key" | tr '/":<>|*?\/\\' '-')
            clean_value=$(echo "$key" | tr '/":<>|*?\/\\' '-')
            echo link $clean_key "->" $clean_value
            ln -s "$clean_value" final/"$clean_key"
          fi
        done

    - name: Upload final Pages artifact
      uses: actions/upload-pages-artifact@v3
      with:
        path: "final/"
    
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4


permissions:
  contents: read
  pages: write
  id-token: write