Initial commit

.editorconfig

@@ -0,0 +1,35 @@
+# https://EditorConfig.org
+
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.ipynb]
+# Content is json, but it seems to be minimally formatted
+indent_size = unset
+
+[*.js]
+indent_size = 2
+
+[*.json]
+indent_size = 2
+
+[*.md]
+indent_size = unset
+
+[*.py]
+# yapf and black will use indents other than 4 spaces
+indent_size = unset
+
+[*.rst]
+indent_size = unset
+
+[{*.yml, *.yaml}]
+indent_size = 2

.github/actions/README.md

@@ -0,0 +1,46 @@
+# eScience Hackweek Jupyterbook Template GitHub Actions
+
+This folder contains continuous integration workflows to perform a variety of tasks such as checking for spelling errors and broken links, ensuring HTML is generated without errors, and publishing the website.
+
+## Actions
+
+the `actions/` subfolder contains common [composite actions steps](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action) that any workflow can use.
+
+#### [setupconda](./actions/setupconda/action.yaml)
+Steps to configure conda environment required to build the website.
+
+#### [buildresources](./actions/buildresources/action.yaml)
+Steps to build the hackweek landing webpage and JupyterBook.
+
+
+## Workflows
+
+The `workflows/` subfolder contains continuous integration workflows
+
+#### [binder-badge.yaml](./actions/workflows/binder-badge.yaml)
+Create [binder](https://mybinder.readthedocs.io/en/latest/howto/gh-actions-badges.html) badges with links to test tutorial notebooks
+
+#### [deploy.yaml](./actions/workflows/deploy.yaml)
+Render and publish the websites (JupyterBook and landing page) to GitHub Pages
+
+#### [manual.yaml](./actions/workflows/manual.yaml)
+Bypass usage of the cache to manually trigger a full rebuild of the JupyterBook and landing page
+
+#### [netlifypreview.yaml](./actions/workflows/netlifypreview.yaml)
+Creates public preview, via [netlify](https://jupyterbook.org/publish/netlify.html), of changes by building from a PR
+
+#### [qaqc.yaml](./actions/workflows/qaqc.yaml)
+Quality assessment and quality control. Standardizes formatting including spell check, hyperlink check, and clearing notebook outputs
+
+#### [repo2docker.yaml](./actions/workflows/repo2docker.yaml)
+[Build a Docker image](https://github.com/jupyterhub/repo2docker-action) for JupyterHub/BinderHub
+
+#### [test.yaml](./actions/workflows/test.yaml)
+Build the websites (JupyterBook and front page). Run on Pull Requests against every commit and via a 'cron' schedule to maintain caching [since otherwise the cache expires if untouched in 7 days](https://docs.github.com/en/actions/advanced-guides/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy)
+
+#### [update_fr_template.yaml](./actions/workflows/update_fr_template.yaml)
+Update the current repo from the original template (`uwhackweek/jupyterbook-template`). Run manually to collect any updates made to template files listed in `.templaterc.json`, commit them to a new branch, and submit a PR the repo created from the template.
+
+## Security
+
+It's desirable for hackweek websites to have contributions from anyone, so the website repository should allow for changes via pull requests from forks. By default workflows running off forked repositories do not have access to secrets, but [following security best practices](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/) you can require adding a label to a pull request in order to run a workflow that requires secrets. For an example, see the [netlifypreview.yaml](./actions/workflows/netlifypreview.yaml) workflow.

.github/actions/buildresources/action.yaml

@@ -0,0 +1,56 @@
+name: 'Build Jupyterbook'
+description: 'Build the Jupyterbook with desired run features'
+
+inputs:
+  jb-cache:
+    description: “Set up the Jupyterbook Cache (boolean)”
+    required: true
+  publish-to-gh:
+    description: “Publish to GitHub Pages (boolean)”
+    required: true
+  jb-save:
+    description: "Save the Jupyterbook Build (boolean)"
+    required: true
+  token:
+    description: 'A GitHub Personal Access Token (for publishing)'
+    required: false
+    default: '0'
+
+runs:
+  using: "composite"
+  steps:
+    - name: Setup JupyterBook Cache
+      if: inputs.jb-cache == 'true'
+      uses: actions/cache@v3
+      with:
+        path: ./book/_build
+        # NOTE: change key to "jupyterbook-N+1" to force rebuilding cache
+        key: jupyterbook-0
+
+    - uses: ./.github/actions/setupconda
+
+    - name: Build JupyterBook
+      shell: bash -l {0}
+      run: |
+        jupyter-book build book
+
+    - name: Dump Build Logs
+      if: always()
+      shell: bash -l {0}
+      run: |
+        if (test -a book/_build/html/reports/*log); then cat book/_build/html/reports/*log ; fi
+
+    - name: Publish to GitHub Pages
+      if: inputs.publish-to-gh == 'true'
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        personal_token: ${{inputs.token}}
+        publish_dir: book/_build/html
+        publish_branch: gh-pages
+
+    - name: Save Build
+      if: ${{ always() && inputs.jb-save == 'true'}}
+      uses: actions/upload-artifact@v2
+      with:
+        name: build
+        path: book/_build/

.github/actions/setupconda/action.yaml

@@ -0,0 +1,44 @@
+name: 'Setup Conda'
+description: 'Create conda environment for GitHub Action Job'
+
+runs:
+  using: "composite"
+  steps:
+    - name: Cache Conda Packages
+      id: cache-packages
+      uses: actions/cache@v3
+      env:
+        # Increase this value to reset cache if conda/conda-lock.yml has not changed
+        CACHE_NUMBER: 0
+      with:
+        path: ~/conda_pkgs_dir
+        key:
+          ${{ runner.os }}-conda-packages-${{ env.CACHE_NUMBER }}-${{ hashFiles('conda/conda-lock.yml') }}
+
+    - name: Setup Mambaforge
+      uses: conda-incubator/setup-miniconda@v2
+      with:
+        miniforge-version: latest
+        miniforge-variant: Mambaforge
+        use-mamba: true
+        auto-update-conda: false
+        activate-environment: geosmart
+        use-only-tar-bz2: true # IMPORTANT: This needs to be set for conda package cache to work properly!
+
+    - name: Cache Entire Conda Environment
+      id: cache-env
+      uses: actions/cache@v3
+      env:
+        CACHE_NUMBER: 0
+      with:
+        path: ${{ env.CONDA }}/envs
+        key:
+          ${{ runner.os }}-conda-environment-${{ env.CACHE_NUMBER }}-${{ hashFiles('conda/conda-lock.yml') }}
+
+    - name: Update Conda Environment
+      if: steps.cache-env.outputs.cache-hit != 'true'
+      env:
+        # ENVFILE: conda/conda-${{ runner.os == 'Linux' && 'linux' || 'osx'  }}-64.lock.yml
+        ENVFILE: conda/environment.yml
+      shell: bash -l {0}
+      run: mamba env update -n geosmart -f $ENVFILE

.github/workflows/binder-badge.yaml

@@ -0,0 +1,38 @@
+name: AddBinderBadge
+# https://github.com/jupyterhub/repo2docker-action#cache-builds-on-mybinderorg-and-provide-a-link
+on:
+  pull_request:
+    types: [opened, reopened]
+    paths:
+      - 'book/tutorials/**'
+      - '.github/workflows/binder-badge.yml'
+      - 'conda/**'
+jobs:
+  add-badge:
+    runs-on: ubuntu-22.04
+    steps:
+    - name: Checkout PR
+      uses: actions/checkout@v3
+
+    - name: cache binder build on mybinder.org
+      uses: jupyterhub/repo2docker-action@master
+      with:
+        NO_PUSH: true
+        MYBINDERORG_TAG: ${{ github.event.pull_request.head.ref }}
+
+    - name: Comment on PR with Binder link
+      uses: actions/github-script@v3
+      env:
+        BRANCH_NAME: ${{ github.event.pull_request.head.ref }}
+        CONTENT_REPO: ${{github.event.pull_request.head.repo.full_name}}
+      with:
+        github-token: ${{secrets.GITHUB_TOKEN}}
+        script: |
+          var BRANCH_NAME = process.env.BRANCH_NAME;
+          var CONTENT_REPO = process.env.CONTENT_REPO;
+          github.issues.createComment({
+            issue_number: context.issue.number,
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            body: `[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/${context.repo.owner}/${context.repo.repo}/${BRANCH_NAME}) :point_left: Launch a binder notebook on this branch`
+          })

.github/workflows/deploy.yaml

@@ -0,0 +1,26 @@
+name: Deploy
+
+on:
+  push:
+    paths:
+      - 'book/**'
+      - '.github/workflows/deploy.yaml'
+      - '.github/actions/**'
+
+    branches:
+      - main
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-22.04
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+
+    - uses: ./.github/actions/buildresources
+      with:
+        jb-cache: false
+        publish-to-gh: true
+        jb-save: true
+        token:  ${{ secrets.GITHUB_TOKEN }}

.github/workflows/ensure_clean_notebooks.py

@@ -0,0 +1,42 @@
+import sys
+from pathlib import Path
+
+import nb_clean as nbc
+import nbformat
+import yaml
+
+with open('./book/_config.yml') as f:
+  data = yaml.safe_load(f)
+
+# Sometimes we use rendered notebooks instead of executing them
+exclude_paths = []
+for pattern in data['execute']['exclude_patterns']:
+    exclude_paths += list(Path('book/tutorials').glob(pattern))
+    exclude_notebooks = [path.as_posix() for path in exclude_paths]
+print('Excluded from execution:\n', '\n'.join(exclude_notebooks))
+
+# Scrub outputs for spellcheck and linkcheck
+for notebook in exclude_notebooks:
+    print(f'Scrubbing outputs: {notebook}...')
+    nb = nbformat.read(notebook, as_version=nbformat.NO_CONVERT)
+    cleaned = nbc.clean_notebook(nb,
+                                 remove_empty_cells=True,
+                                 preserve_cell_metadata=True)
+    nbformat.write(cleaned, notebook)
+
+
+all_ipynbs = [path.as_posix() for path in Path('book/tutorials').rglob('*.ipynb')]
+ipynbs = [p for p in all_ipynbs if not '.ipynb_checkpoints' in p]
+
+results = []
+for notebook in ipynbs:
+    #if not notebook in exclude_notebooks:
+    print(f'Checking {notebook}...')
+    nb = nbformat.read(notebook, as_version=nbformat.NO_CONVERT)
+    result = nbc.check_notebook(nb,
+                                remove_empty_cells=True,
+                                preserve_cell_metadata=True)
+    results.append(result)
+
+if False in results:
+    sys.exit(1)

.github/workflows/manual.yaml

@@ -0,0 +1,18 @@
+name: Build Without Cache
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+
+    - uses: ./.github/actions/buildresources
+      with:
+        jb-cache: false
+        publish-to-gh: false
+        jb-save: true

.github/workflows/netlifypreview.yaml

@@ -0,0 +1,40 @@
+name: NetlifyPreview
+
+on:
+  pull_request_target:
+    types: [labeled, synchronize]
+
+jobs:
+  add-preview:
+    runs-on: ubuntu-latest
+    # This workflow accesses secrets and checks out a PR, so only run if labelled
+    # https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
+    if: contains(github.event.pull_request.labels.*.name, 'preview')
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+      with:
+        ref: ${{ github.event.pull_request.head.sha }}
+
+    - uses: ./.github/actions/buildresources
+      with:
+        jb-cache: false
+        publish-to-gh: false
+        jb-save: false
+
+    - name: Deploy Website Preview
+      uses: nwtgck/[email protected]
+      with:
+        publish-dir: './book/_build/html'
+        production-deploy: false
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        deploy-message: "Deploy from GitHub Actions"
+        enable-commit-comment: false
+        enable-pull-request-comment: true
+        overwrites-pull-request-comment: true
+        alias: deploy-preview-${{ github.event.number }}
+      env:
+        NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+        NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+      timeout-minutes: 1