Initial commit

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  # - package-ecosystem: pip
+  #   directory: "/"
+  #   schedule:
+  #     interval: daily
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      # Check for updates once a week
+      interval: 'weekly'

.github/workflows/build-book.yaml

@@ -0,0 +1,76 @@
+name: build-book
+
+on:
+  workflow_call:
+    inputs:
+      environment_name:
+        description: 'Name of conda environment to activate'
+        required: false
+        default: 'cookbook-dev'
+        type: string
+      environment_file:
+        description: 'Name of conda environment file'
+        required: false
+        default: 'environment.yml'
+        type: string
+      path_to_notebooks:
+        description: 'Location of the JupyterBook source relative to repo root'
+        required: false
+        default: './'
+        type: string
+      use_cached_environment:
+        description: 'Flag for whether we should attempt to retrieve a previously cached environment.'
+        required: false
+        default: 'true'
+        type: string  # had a lot of trouble with boolean types, see https://github.com/actions/runner/issues/1483
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Mambaforge
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          miniforge-variant: Mambaforge
+          miniforge-version: latest
+          activate-environment: ${{ inputs.environment_name }}
+          use-mamba: true
+
+      - name: Set cache date
+        if: ${{ inputs.use_cached_environment == 'true' }}
+        run: echo "DATE=$(date +'%Y%m%d')" >> $GITHUB_ENV
+
+      - uses: actions/cache@v3
+        if: inputs.use_cached_environment == 'true'
+        with:
+          path: /usr/share/miniconda3/envs/${{ inputs.environment_name }}
+          key: linux-64-conda-${{ hashFiles('${{ inputs.environment_file }}') }}-${{ env.DATE }}
+        id: cache
+
+      - name: Update environment
+        if: |
+          inputs.use_cached_environment != 'true'
+          || steps.cache.outputs.cache-hit != 'true'
+        run: mamba env update -n ${{ inputs.environment_name }} -f ${{ inputs.environment_file }}
+
+      - name: Build the book
+        run: |
+          jupyter-book build ${{ inputs.path_to_notebooks }}
+      - name: Zip the book
+        run: |
+          set -x
+          set -e
+          if [ -f book.zip ]; then
+              rm -rf book.zip
+          fi
+          zip -r book.zip ${{ inputs.path_to_notebooks }}/_build/html
+      - name: Upload zipped book artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: book-zip-${{github.event.number}}
+          path: ./book.zip

.github/workflows/delete-preview.yaml

@@ -0,0 +1,26 @@
+name: delete-preview
+
+# Only run this when the main branch changes
+on:
+  pull_request_target:
+    types: closed
+
+jobs:
+  delete:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+      - name: Delete preview files
+        run: |
+          rm -rf _preview/${{ github.event.pull_request.number }}
+      - name: Commit the changes
+        uses: stefanzweifel/git-auto-commit-action@v4
+        with:
+          branch: gh-pages
+          commit_message: Delete preview for pull request \#${{ github.event.pull_request.number }}

.github/workflows/deploy-book.yaml

@@ -0,0 +1,42 @@
+name: deploy-book
+
+on:
+  # Trigger the workflow on push to main branch
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  build:
+    uses: ./.github/workflows/build-book.yaml
+    with:
+      environment_name: cookbook-dev
+      environment_file: environment.yml
+      path_to_notebooks: notebooks/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps:
+      - name: Download Artifact Book
+        uses: actions/download-artifact@v3
+        with:
+          name: book-zip-${{ github.event.number }}
+
+      - name: Unzip the book
+        run: |
+          rm -rf notebooks/_build/html
+          unzip book.zip
+          rm -f book.zip
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/[email protected]
+        if: github.ref == 'refs/heads/main'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: notebooks/_build/html
+          keep_files: true  # This preserves existing previews from open PRs

.github/workflows/deploy-preview.yaml

@@ -0,0 +1,137 @@
+name: deploy-preview
+on:
+  workflow_run:
+    workflows:
+      - trigger-book-build
+    types:
+      - requested
+      - completed
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps:
+      - uses: actions/checkout@v3
+      - name: Fetch Repo Name
+        id: repo-name
+        run: echo "::set-output name=value::$(echo '${{ github.repository }}' | awk -F '/' '{print $2}')"  # just the repo name, not owner
+
+      - name: Set message value
+        run: |
+          echo "comment_message=👋 Thanks for opening this PR! The Cookbook will be automatically built with [GitHub Actions](https://github.com/features/actions). To see the status of your deployment, click below." >> $GITHUB_ENV
+
+      - name: Find Pull Request
+        uses: actions/github-script@v6
+        id: find-pull-request
+        with:
+          script: |
+            let pullRequestNumber = ''
+            let pullRequestHeadSHA = ''
+            core.info('Finding pull request...')
+            const pullRequests = await github.rest.pulls.list({owner: context.repo.owner, repo: context.repo.repo})
+            for (let pullRequest of pullRequests.data) {
+              if(pullRequest.head.sha === context.payload.workflow_run.head_commit.id) {
+                  pullRequestHeadSHA = pullRequest.head.sha
+                  pullRequestNumber = pullRequest.number
+                  break
+              }
+            }
+            core.setOutput('number', pullRequestNumber)
+            core.setOutput('sha', pullRequestHeadSHA)
+            if(pullRequestNumber === '') {
+              core.info(
+                 `No pull request associated with git commit SHA: ${context.payload.workflow_run.head_commit.id}`
+              )
+            }
+            else{
+              core.info(`Found pull request ${pullRequestNumber}, with head sha: ${pullRequestHeadSHA}`)
+            }
+
+      - name: Find preview comment
+        uses: peter-evans/find-comment@v2
+        if: steps.find-pull-request.outputs.number != ''
+        id: fc
+        with:
+          issue-number: '${{ steps.find-pull-request.outputs.number }}'
+          comment-author: 'github-actions[bot]'
+          body-includes: '${{ env.comment_message }}'
+
+      - name: Create preview comment
+        if: |
+          github.event.workflow_run.conclusion != 'success'
+          && steps.find-pull-request.outputs.number != ''
+          && steps.fc.outputs.comment-id == ''
+        uses: peter-evans/create-or-update-comment@v2
+        with:
+          issue-number: ${{ steps.find-pull-request.outputs.number }}
+          body: |
+            ${{ env.comment_message }}
+            🔍 Git commit SHA: ${{ steps.find-pull-request.outputs.sha }}
+            ✅ Deployment Preview URL: In Progress
+
+      - name: Update preview comment
+        if: |
+          github.event.workflow_run.conclusion != 'success'
+          && steps.find-pull-request.outputs.number != ''
+          && steps.fc.outputs.comment-id != ''
+        uses: peter-evans/create-or-update-comment@v2
+        with:
+          comment-id: ${{ steps.fc.outputs.comment-id }}
+          edit-mode: replace
+          body: |
+            ${{ env.comment_message }}
+            🔍 Git commit SHA: ${{ steps.find-pull-request.outputs.sha }}
+            ✅ Deployment Preview URL: In Progress
+
+      - name: Download Artifact Book
+        if: |
+          github.event.workflow_run.conclusion == 'success'
+          && steps.find-pull-request.outputs.number != ''
+          && steps.fc.outputs.comment-id != ''
+        uses: dawidd6/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          workflow: build-book.yaml
+          run_id: ${{ github.event.workflow_run.id }}
+          name: book-zip-${{ steps.find-pull-request.outputs.number }}
+
+      - name: Unzip the book
+        if: |
+          github.event.workflow_run.conclusion == 'success'
+          && steps.find-pull-request.outputs.number != ''
+          && steps.fc.outputs.comment-id != ''
+        run: |
+          rm -rf notebooks/_build/html
+          unzip book.zip
+          rm -f book.zip
+
+      # Push the book's HTML to github-pages
+      # This will be published at /_preview/PRnumber/ relative to the main site
+      - name: Deploy to GitHub pages
+        if: |
+          github.event.workflow_run.conclusion == 'success'
+          && steps.find-pull-request.outputs.number != ''
+          && steps.fc.outputs.comment-id != ''
+        uses: peaceiris/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: notebooks/_build/html
+          enable_jekyll: false
+          destination_dir: _preview/${{ steps.find-pull-request.outputs.number }}
+
+      - name: Finalize preview comment
+        if: |
+          github.event.workflow_run.conclusion == 'success'
+          && steps.find-pull-request.outputs.number != ''
+          && steps.fc.outputs.comment-id != ''
+        uses: peter-evans/create-or-update-comment@v2
+        with:
+          comment-id: ${{ steps.fc.outputs.comment-id }}
+          edit-mode: replace
+          body: |
+            ${{ env.comment_message }}
+            🔍 Git commit SHA: ${{ steps.find-pull-request.outputs.sha }}
+            ✅ Deployment Preview URL: https://${{ github.repository_owner }}.github.io/${{ steps.repo-name.outputs.value }}/_preview/${{ steps.find-pull-request.outputs.number }}

.github/workflows/link-checker.yaml

@@ -0,0 +1,76 @@
+name: link-checker
+
+on:
+  workflow_call:
+    inputs:
+      environment_name:
+        description: 'Name of conda environment to activate'
+        required: false
+        default: 'cookbook-dev'
+        type: string
+      environment_file:
+        description: 'Name of conda environment file'
+        required: false
+        default: 'environment.yml'
+        type: string
+      path_to_notebooks:
+        description: 'Location of the JupyterBook source relative to repo root'
+        required: false
+        default: './'
+        type: string
+      use_cached_environment:
+        description: 'Flag for whether we should attempt to retrieve a previously cached environment.'
+        required: false
+        default: 'true'
+        type: string
+
+jobs:
+  link-checker:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps:
+      - name: Cancel previous runs
+        uses: styfle/[email protected]
+        with:
+          access_token: ${{ github.token }}
+      - uses: actions/checkout@v3
+
+      - name: Setup Mambaforge
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          miniforge-variant: Mambaforge
+          miniforge-version: latest
+          activate-environment: ${{ inputs.environment_name }}
+          use-mamba: true
+
+      - name: Set cache date
+        if: inputs.use_cached_environment == 'true'
+        run: echo "DATE=$(date +'%Y%m%d')" >> $GITHUB_ENV
+
+      - uses: actions/cache@v3
+        if: inputs.use_cached_environment == 'true'
+        with:
+          path: /usr/share/miniconda3/envs/${{ inputs.environment_name }}
+          key: linux-64-conda-${{ hashFiles('${{ inputs.environment_file }}') }}-${{ env.DATE }}
+        id: cache
+
+      - name: Update environment
+        if: |
+          inputs.use_cached_environment != 'true'
+          || steps.cache.outputs.cache-hit != 'true'
+        run: mamba env update -n ${{ inputs.environment_name }} -f ${{ inputs.environment_file }}
+
+      - name: Disable notebook execution
+        shell: python
+        run: |
+          import yaml
+          with open('${{ inputs.path_to_notebooks }}/_config.yml') as f:
+            data = yaml.safe_load(f)
+          data['execute']['execute_notebooks'] = 'off'
+          with open('${{ inputs.path_to_notebooks }}/_config.yml', 'w') as f:
+            yaml.dump(data, f)
+      - name: Check external links
+        run: |
+          jupyter-book build --builder linkcheck ${{ inputs.path_to_notebooks }}

.github/workflows/nightly-build.yaml

@@ -0,0 +1,21 @@
+name: nightly-build
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0 * * *' # Daily “At 00:00”
+
+jobs:
+  build:
+    uses: ./.github/workflows/build-book.yaml
+    with:
+      environment_name: cookbook-dev
+      environment_file: environment.yml
+      path_to_notebooks: notebooks/
+
+  link-check:
+    uses: ./.github/workflows/link-checker.yaml
+    with:
+      environment_name: cookbook-dev
+      environment_file: environment.yml
+      path_to_notebooks: notebooks/