From 3c0fb4389ed0348b50046be85d20f6963620b4fc Mon Sep 17 00:00:00 2001 From: Severin Date: Tue, 2 Apr 2024 19:57:10 +0200 Subject: [PATCH 01/10] Cache book builds --- .github/workflows/deploy-book-ghpages.yml | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/.github/workflows/deploy-book-ghpages.yml b/.github/workflows/deploy-book-ghpages.yml index 8f35af3..9661c83 100644 --- a/.github/workflows/deploy-book-ghpages.yml +++ b/.github/workflows/deploy-book-ghpages.yml @@ -50,17 +50,27 @@ jobs: with: ref: ${{ matrix.branch }} - # Install dependencies - - name: Set up Python 3.11 + - 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' - - 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/ From 3bc40cc4b9e72ba409a282430c95d0db32ccd4b5 Mon Sep 17 00:00:00 2001 From: Severin Date: Tue, 2 Apr 2024 19:57:37 +0200 Subject: [PATCH 02/10] Preprocess with teachbooks pkg --- .github/workflows/deploy-book-ghpages.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/deploy-book-ghpages.yml b/.github/workflows/deploy-book-ghpages.yml index 9661c83..fb3f1b6 100644 --- a/.github/workflows/deploy-book-ghpages.yml +++ b/.github/workflows/deploy-book-ghpages.yml @@ -72,6 +72,12 @@ jobs: - if: ${{ steps.cache-html.outputs.cache-hit != 'true' }} name: Preprocess & build the book from branch run: | + echo $PATH + pip install --user teachbooks --extra-index-url https://gitlab.tudelft.nl/api/v4/projects/13957/packages/pypi/simple + cat book/_toc.yml + teachbooks build --publish --process-only book/ + mv book/.psorbooks/publish/_toc.yml book/.psorbooks/publish/_config.yml book/ + cat book/_toc.yml jupyter-book build book/ - name: Upload the built book HTML as an artifact From 01d0f3943f0206cc00c98fe819b5b7c37e339145 Mon Sep 17 00:00:00 2001 From: Severin Date: Tue, 2 Apr 2024 19:59:06 +0200 Subject: [PATCH 03/10] Make primary branch accessible at page root --- .github/workflows/deploy-book-ghpages.yml | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/.github/workflows/deploy-book-ghpages.yml b/.github/workflows/deploy-book-ghpages.yml index fb3f1b6..a2a9209 100644 --- a/.github/workflows/deploy-book-ghpages.yml +++ b/.github/workflows/deploy-book-ghpages.yml @@ -105,11 +105,15 @@ 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 - ln -s main final/book + 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: Load root page to redirect to `book/` run: | From 943ed05bf4323ec467f4c801e1ccbffe109815d7 Mon Sep 17 00:00:00 2001 From: Severin Date: Tue, 2 Apr 2024 20:00:05 +0200 Subject: [PATCH 04/10] Add rules for branches 1. User can set the "primary" branch to live at page root. This is `publish` by default. 2. User can set a list of aliases (symbolic links). The default setting maps `draft` to `main`, and `book` to `publish`. 3. User can set a list of branch to be deployed. By default: deploy all branches (indicated by '*'). NOTE: If user wants no branches deployed, or no aliases, they can set the corresponding variables to ' '. --- .github/workflows/deploy-book-ghpages.yml | 35 ++++++++++++++++++++--- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/.github/workflows/deploy-book-ghpages.yml b/.github/workflows/deploy-book-ghpages.yml index a2a9209..7544985 100644 --- a/.github/workflows/deploy-book-ghpages.yml +++ b/.github/workflows/deploy-book-ghpages.yml @@ -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' | 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 @@ -115,9 +135,16 @@ jobs: 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 From daef8d192faf78304238592fb0377ba136137e3c Mon Sep 17 00:00:00 2001 From: Severin Date: Tue, 2 Apr 2024 23:21:08 +0200 Subject: [PATCH 05/10] Del redirect --- redirect.html | 15 --------------- 1 file changed, 15 deletions(-) delete mode 100644 redirect.html diff --git a/redirect.html b/redirect.html deleted file mode 100644 index 2694115..0000000 --- a/redirect.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - - - - - From 56b155c59e9abb51fff7ed900de8e6da0ed45b39 Mon Sep 17 00:00:00 2001 From: Severin Date: Wed, 3 Apr 2024 14:36:55 +0200 Subject: [PATCH 06/10] Run on push on all branches --- .github/workflows/deploy-book-ghpages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy-book-ghpages.yml b/.github/workflows/deploy-book-ghpages.yml index 7544985..264e988 100644 --- a/.github/workflows/deploy-book-ghpages.yml +++ b/.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. From 70b333585e689d665f3ee8fd6605c09d218e004d Mon Sep 17 00:00:00 2001 From: Severin Date: Wed, 3 Apr 2024 14:38:22 +0200 Subject: [PATCH 07/10] Clean branch name from spec chars --- .github/workflows/deploy-book-ghpages.yml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.github/workflows/deploy-book-ghpages.yml b/.github/workflows/deploy-book-ghpages.yml index 264e988..90d8ea5 100644 --- a/.github/workflows/deploy-book-ghpages.yml +++ b/.github/workflows/deploy-book-ghpages.yml @@ -48,7 +48,7 @@ jobs: 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' | jq -Rn '[inputs]') + branches=$(echo "$BRANCHES_TO_DEPLOY" | tr ' ' '\n' | grep -E '\S' | jq -Rn '[inputs]') fi echo "branches=$(echo $branches)" >> $GITHUB_OUTPUT @@ -100,10 +100,14 @@ jobs: cat book/_toc.yml jupyter-book build book/ + - 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: From 67659646d110d8378773cd693c4dcd32198e524a Mon Sep 17 00:00:00 2001 From: Severin Date: Wed, 3 Apr 2024 15:46:47 +0200 Subject: [PATCH 08/10] Correct aliasing --- .github/workflows/deploy-book-ghpages.yml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/deploy-book-ghpages.yml b/.github/workflows/deploy-book-ghpages.yml index 90d8ea5..e1c1e84 100644 --- a/.github/workflows/deploy-book-ghpages.yml +++ b/.github/workflows/deploy-book-ghpages.yml @@ -141,11 +141,11 @@ jobs: - name: Symlink branch aliases run: | - echo $BRANCH_ALIASES | tr ' ' '\n' | { grep -E '\S' | :; } | + 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 + echo link $key "->" $value ln -s $value final/$key fi done @@ -163,4 +163,5 @@ jobs: permissions: contents: read pages: write - id-token: write \ No newline at end of file + id-token: write + From b9e8e71a59444877bac189549176643a7cc15cb3 Mon Sep 17 00:00:00 2001 From: Severin Date: Wed, 3 Apr 2024 18:13:35 +0200 Subject: [PATCH 09/10] Fix teachbooks usage --- .github/workflows/deploy-book-ghpages.yml | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/.github/workflows/deploy-book-ghpages.yml b/.github/workflows/deploy-book-ghpages.yml index e1c1e84..a63e508 100644 --- a/.github/workflows/deploy-book-ghpages.yml +++ b/.github/workflows/deploy-book-ghpages.yml @@ -93,12 +93,17 @@ jobs: name: Preprocess & build the book from branch run: | echo $PATH + # Install wrapper + # NOTE: teachbooks is already installed w requirements.txt, however not on PATH + # Installing with --user fixes this. + # TODO remove --extra-index-url once teachbooks is on PyPI pip install --user teachbooks --extra-index-url https://gitlab.tudelft.nl/api/v4/projects/13957/packages/pypi/simple - cat book/_toc.yml - teachbooks build --publish --process-only book/ - mv book/.psorbooks/publish/_toc.yml book/.psorbooks/publish/_config.yml book/ - cat book/_toc.yml - jupyter-book build book/ + if [ ${{matrix.branch}} == $PRIMARY_BRANCH ]; then + teachbooks build --publish book/ + else + teachbooks build book/ + fi + - name: Clean branch name of disallowed characters run: | From 733fa8a6d4efb79a255c6b9490f07cdc8ee5355d Mon Sep 17 00:00:00 2001 From: Caspar Jungbacker <74240267+CasparJungbacker@users.noreply.github.com> Date: Thu, 4 Apr 2024 15:18:29 +0200 Subject: [PATCH 10/10] [Feature] Use PyPI version of `teachbooks` --- .github/workflows/deploy-book-ghpages.yml | 5 ----- requirements.txt | 2 +- 2 files changed, 1 insertion(+), 6 deletions(-) diff --git a/.github/workflows/deploy-book-ghpages.yml b/.github/workflows/deploy-book-ghpages.yml index a63e508..92a90b3 100644 --- a/.github/workflows/deploy-book-ghpages.yml +++ b/.github/workflows/deploy-book-ghpages.yml @@ -93,11 +93,6 @@ jobs: name: Preprocess & build the book from branch run: | echo $PATH - # Install wrapper - # NOTE: teachbooks is already installed w requirements.txt, however not on PATH - # Installing with --user fixes this. - # TODO remove --extra-index-url once teachbooks is on PyPI - pip install --user teachbooks --extra-index-url https://gitlab.tudelft.nl/api/v4/projects/13957/packages/pypi/simple if [ ${{matrix.branch}} == $PRIMARY_BRANCH ]; then teachbooks build --publish book/ else diff --git a/requirements.txt b/requirements.txt index 2482e95..5917367 100644 --- a/requirements.txt +++ b/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