Merge pull request #12 from TeachBooks/feat/10/aliases-and-caching

Let's merge this and create follow-up issues

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

@@ -7,7 +7,7 @@ name: deploy-book
 on:
   push:
     branches:
-    - '*'
+    - '**'
     # If your git repository has the Jupyter Book within some-subfolder next to
     # unrelated files, you can make this run only if a file within that specific
     # folder has been modified.
@@ -16,6 +16,20 @@ on:
     # - some-subfolder/**
   workflow_dispatch:
 
+# 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:
+  # `publish` as primary by default
+  PRIMARY_BRANCH: ${{ vars.PRIMARY_BRANCH != '' && vars.PRIMARY_BRANCH || 'publish' }}
+  # Space-separated list of alias-rules, e.g. 'draft:main alias:really-long-branch-name'
+  # By default, `draft` links to `main`.
+  # If no aliases are wanted, BRANCH_ALIASES may be set to ' ' (space).
+  BRANCH_ALIASES: ${{ vars.BRANCH_ALIASES != '' && vars.BRANCH_ALIASES || 'draft:main book:publish' }}
+  # 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
@@ -27,15 +41,21 @@ jobs:
     - uses: actions/checkout@v4
       with:
         fetch-depth: 0
+
     - id: set-branches
-      name: Collect all remote branch names for the matrix
+      name: Set branches
       run: |
-        branches=$(git branch -r | sed 's,\s*origin/,,g' | jq -Rn '[inputs]')
+        if [ "$BRANCHES_TO_DEPLOY" == '*' ]; then
+          branches=$(git branch -r | sed 's,\s*origin/,,g' | jq -Rn '[inputs]')
+        else
+          branches=$(echo "$BRANCHES_TO_DEPLOY" | tr ' ' '\n' | grep -E '\S' | jq -Rn '[inputs]')
+        fi
         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
@@ -50,24 +70,44 @@ jobs:
       with:
         ref: ${{ matrix.branch }}
 
-    # Install dependencies
+    - name: Cache page build
-    - name: Set up Python 3.11
+      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'
 
-    - name: Install dependencies
+    - if: ${{ steps.cache-html.outputs.cache-hit != 'true' }}
+      name: Install dependencies
       run: |
         pip install -r requirements.txt
 
-    - name: Build the book from branch
+    - if: ${{ steps.cache-html.outputs.cache-hit != 'true' }}
+      name: Preprocess & build the book from branch
       run: |
-        jupyter-book build book/
+        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: ${{ matrix.branch }}
+        name: ${{ env.MATRIX_BRANCH_NAME_CLEAN }}
         path: "book/_build/html"
 
   deploy-books:
@@ -89,15 +129,26 @@ jobs:
       with:
         path: "final/"
 
-    - name: Symlink `book` to `main`
+    - name: Copy primary book to root, fail if names conflict
+      timeout-minutes: 1
       run: |
-        if test -d final/main; then
+        GLOBIGNORE=".:.."
-          ln -s main final/book
+        # -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: Load root page to redirect to `book/`
+    - name: Symlink branch aliases
       run: |
-        cp redirect.html final/index.html
+        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
+            echo link $key "->" $value
+            ln -s $value final/$key
+          fi
+        done
 
     - name: Upload final Pages artifact
       uses: actions/upload-pages-artifact@v3
@@ -113,3 +164,4 @@ permissions:
   contents: read
   pages: write
   id-token: write
+

redirect.html

@@ -1,15 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-</head>
-<body>
-    <script>
-        pattern = /^https?:\/\/[\w-\.]+\.github\.io\/[\w-\.]+\/?$/
-        if (pattern.test(window.location.href)) {
-            window.location.href = window.location.href + "book/";
-        }
-    </script>
-</body>
-</html>

requirements.txt

@@ -1,5 +1,5 @@
 # first list the packages you wish to download from PyPI
-jupyter-book
+teachbooks # depends on jupyter-book
 # numpy
 
 # docutils version for reference page formatting