diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..b4b3fa4 --- /dev/null +++ b/.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' diff --git a/.github/workflows/build-book.yaml b/.github/workflows/build-book.yaml new file mode 100644 index 0000000..b52f195 --- /dev/null +++ b/.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 diff --git a/.github/workflows/delete-preview.yaml b/.github/workflows/delete-preview.yaml new file mode 100644 index 0000000..2123ac2 --- /dev/null +++ b/.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 }} diff --git a/.github/workflows/deploy-book.yaml b/.github/workflows/deploy-book.yaml new file mode 100644 index 0000000..48e4c79 --- /dev/null +++ b/.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/actions-gh-pages@v3.8.0 + 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 diff --git a/.github/workflows/deploy-preview.yaml b/.github/workflows/deploy-preview.yaml new file mode 100644 index 0000000..538c131 --- /dev/null +++ b/.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/action-download-artifact@v2.21.1 + 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/actions-gh-pages@v3.8.0 + 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 }} diff --git a/.github/workflows/link-checker.yaml b/.github/workflows/link-checker.yaml new file mode 100644 index 0000000..edb0ac8 --- /dev/null +++ b/.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/cancel-workflow-action@0.10.0 + 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 }} diff --git a/.github/workflows/nightly-build.yaml b/.github/workflows/nightly-build.yaml new file mode 100644 index 0000000..b5e6aac --- /dev/null +++ b/.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/ diff --git a/.github/workflows/trigger-book-build.yaml b/.github/workflows/trigger-book-build.yaml new file mode 100644 index 0000000..c83f56d --- /dev/null +++ b/.github/workflows/trigger-book-build.yaml @@ -0,0 +1,19 @@ +name: trigger-book-build +on: + pull_request: + +jobs: + build: + uses: ./.github/workflows/build-book.yaml + with: + environment_name: cookbook-dev + environment_file: environment.yml + path_to_notebooks: notebooks/ + use_cached_environment: 'true' # This is default, not strickly needed. Set to 'false' to always build a new environment + link-check: + uses: ./.github/workflows/link-checker.yaml + with: + environment_name: cookbook-dev + environment_file: environment.yml + path_to_notebooks: notebooks/ + use_cached_environment: 'true' diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b6e4761 --- /dev/null +++ b/.gitignore @@ -0,0 +1,129 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +pip-wheel-metadata/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +.python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f9e4f18 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,34 @@ +# Project Pythia Cookbook Contributor's Guide + +Project Pythia Cookbooks are collections of more advanced and domain-specific example +workflows building on top of [Pythia Foundations](https://foundations.projectpythia.org/landing-page.html). +They are [geoscience](https://en.wikipedia.org/wiki/Earth_science)-focused +and should direct the reader towards the [Foundations material](https://foundations.projectpythia.org/landing-page.html) for any required +background knowledge. + +The following is a step-by-step guide to getting your cookbook idea +hosted on the [Project Pythia Cookbooks gallery](https://projectpythia.org/cookbook-gallery.html). + +1. Use the template + 1. If you don't already have a GitHub account, create one by following the [Getting Started with GitHub guide](https://foundations.projectpythia.org/foundations/getting-started-github.html) + 1. On https://github.com/ProjectPythiaTutorials/cookbook-template, click "Use this template" + 1. Choose "Include all branches" + 1. Create the repo under your account with a descriptive name, followed by `-cookbook` (e.g. `hydrology-cookbook`, `hpc-cookbook`, `cesm-cookbook`, etc.) by entering a name into the "Repository name" field and clicking on "Create repository from template" + 1. Your browser should be directed to the newly created repository under your GitHub account. Under Settings, enable GitHub Pages by changing the Source from "None" to `gh-pages` and clicking on "Save" + 1. [Clone the repo](https://foundations.projectpythia.org/foundations/github/github-cloning-forking.html) in your local workspace and `cd` into your cookbook directory +1. Create the environment + 1. Edit `environment.yml`: change the name to `-dev` (e.g. `cesm-cookbook-dev`) and add all required libraries and other dependencies under `dependencies:`. Commit the changes + 1. Create the Conda environment with `conda env create -f environment.yml`. If it crashes, try running `conda config --set channel_priority strict` + 1. Activate your environment with `conda activate ` +1. Add content + 1. After [creating a new git branch](https://foundations.projectpythia.org/foundations/github/git-branches.html), edit (and duplicate as necessary) the notebook template `notebooks/notebook-template.ipynb` to add your content. Add folders to organize notebooks into sections if applicable + 1. Add the notebooks to `_toc.yml`. See [`radar-cookbook/notebooks/_toc.yml`](https://github.com/ProjectPythiaTutorials/radar-cookbook/blob/main/notebooks/_toc.yml) for syntax + 1. Change `README.md` to include your cookbook title, various badges, a sentence or two describing the cookbook, and a link to the landing page. See the [Radar Cookbook](https://github.com/ProjectPythiaTutorials/radar-cookbook/blob/main/README.md) for an example + 1. Commit your changes with git, and [open a Pull Request](https://foundations.projectpythia.org/foundations/github/github-pull-request.html) on your cookbook repo. When you open a PR there, the github-actions bot will comment a link to a preview of your cookbook +1. Transfer cookbook to the [ProjectPythiaTutorials](https://github.com/ProjectPythiaTutorials) organization + 1. Navigate to the settings of your repo, scroll down to the Danger Zone, and click "Transfer" + 1. For ProjectPythiaTutorials owners or members: type "ProjectPythiaTutorials", confirm, and transfer. + 1. For outside contributors: + 1. Contact an owner of ProjectPythiaTutorials to be added as an outside collaborator. Then transfer to ProjectPythiaTutorials; or + 1. Type the username of an owner or member. They will then tranfer it to ProjectPythiaTutorials and add you as an outside collaborator on that repo + 1. Open issues, PRs, and continue making edits as necessary \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..261eeb9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md new file mode 100644 index 0000000..698857a --- /dev/null +++ b/README.md @@ -0,0 +1,11 @@ +# Cookbook Template + +[![nightly-build](https://github.com/ProjectPythiaTutorials/cookbook-template/actions/workflows/nightly-build.yaml/badge.svg)](https://github.com/ProjectPythiaTutorials/cookbook-template/actions/workflows/nightly-build.yaml) + +This is a template for creating [Project Pythia](https://projectpythia.org) Cookbooks. + +This repository includes all the basic infrastructure to create your content and host it online. You can use this template by selecting the green "Use this Template" button at the top of the page. + +You can use the `notebook-template` in `/notebooks` as your content template! + +Once you have made your new content, add it to the table of contents (`notebooks/_toc.yml`) file, and push it to Github! diff --git a/environment.yml b/environment.yml new file mode 100644 index 0000000..49fe2c2 --- /dev/null +++ b/environment.yml @@ -0,0 +1,8 @@ +name: cookbook-dev +channels: + - conda-forge +dependencies: + - jupyter-book + - pip + - pip: + - sphinx-pythia-theme diff --git a/notebooks/_config.yml b/notebooks/_config.yml new file mode 100644 index 0000000..efc486a --- /dev/null +++ b/notebooks/_config.yml @@ -0,0 +1,68 @@ +# Book settings +# Learn more at https://jupyterbook.org/customize/config.html + +title: Pythia Foundations +author: the Project Pythia Community +logo: images/logos/pythia_logo-white-rtext.svg +email: projectpythia@ucar.edu +copyright: '2022' + +# Don't execute the notebooks upon building the book +execute: + execute_notebooks: "off" + +# Add a few extensions to help with parsing content +parse: + myst_enable_extensions: # default extensions to enable in the myst parser. See https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html + - amsmath + - colon_fence + - deflist + - dollarmath + - html_admonition + - html_image + - replacements + - smartquotes + - substitution + +sphinx: + config: + html_favicon: images/icons/favicon.ico + html_last_updated_fmt: '%-d %B %Y' + html_theme: sphinx_pythia_theme + html_permalinks_icon: '' + html_theme_options: + home_page_in_toc: true + repository_url: https://github.com/ProjectPythia/pythia-foundations # Online location of your book + repository_branch: main # Which branch of the repository should be used when creating links (optional) + use_issues_button: true + use_repository_button: true + use_edit_page_button: true + github_url: https://github.com/ProjectPythia + twitter_url: https://twitter.com/project_pythia + icon_links: + - name: YouTube + url: https://www.youtube.com/channel/UCoZPBqJal5uKpO8ZiwzavCw + icon: fab fa-youtube-square + type: fontawesome + launch_buttons: + binderhub_url: https://mybinder.org + notebook_interface: jupyterlab + extra_navbar: | + Theme by Project Pythia.

+ All code in Pythia Cookbooks is licensed under Apache 2.0. All other non-code content is licensed under Creative Commons BY 4.0 (CC BY 4.0).

+ logo_link: https://projectpythia.org + navbar_links: + - name: Home + url: https://projectpythia.org + - name: Foundations + url: https://foundations.projectpythia.org + - name: Cookbooks + url: https://projectpythia.org/cookbook-gallery.html + - name: Resources + url: https://projectpythia.org/resource-gallery.html + - name: Community + url: https://projectpythia.org/index.html#join-us + footer_logos: + NCAR: images/logos/NCAR-contemp-logo-blue.svg + Unidata: images/logos/Unidata_logo_horizontal_1200x300.svg + UAlbany: images/logos/UAlbany-A2-logo-purple-gold.svg diff --git a/notebooks/_toc.yml b/notebooks/_toc.yml new file mode 100644 index 0000000..1319fc1 --- /dev/null +++ b/notebooks/_toc.yml @@ -0,0 +1,6 @@ +format: jb-book +root: landing-page +parts: + - caption: Introduction + chapters: + - file: notebook-template diff --git a/notebooks/images/ProjectPythia_Logo_Final-01-Blue.svg b/notebooks/images/ProjectPythia_Logo_Final-01-Blue.svg new file mode 100644 index 0000000..961efc2 --- /dev/null +++ b/notebooks/images/ProjectPythia_Logo_Final-01-Blue.svg @@ -0,0 +1 @@ + diff --git a/notebooks/images/icons/favicon.ico b/notebooks/images/icons/favicon.ico new file mode 100644 index 0000000..da6ac73 Binary files /dev/null and b/notebooks/images/icons/favicon.ico differ diff --git a/notebooks/images/logos/NCAR-contemp-logo-blue.svg b/notebooks/images/logos/NCAR-contemp-logo-blue.svg new file mode 100644 index 0000000..3bcda63 --- /dev/null +++ b/notebooks/images/logos/NCAR-contemp-logo-blue.svg @@ -0,0 +1 @@ +NCAR-contemp-logo-blue.a diff --git a/notebooks/images/logos/UAlbany-A2-logo-purple-gold.svg b/notebooks/images/logos/UAlbany-A2-logo-purple-gold.svg new file mode 100644 index 0000000..4fdfe3a --- /dev/null +++ b/notebooks/images/logos/UAlbany-A2-logo-purple-gold.svg @@ -0,0 +1,1125 @@ + + + + + + image/svg+xml + + + + + + + + + + + diff --git a/notebooks/images/logos/Unidata_logo_horizontal_1200x300.svg b/notebooks/images/logos/Unidata_logo_horizontal_1200x300.svg new file mode 100644 index 0000000..0d9fd70 --- /dev/null +++ b/notebooks/images/logos/Unidata_logo_horizontal_1200x300.svg @@ -0,0 +1,891 @@ + + + + + + image/svg+xml + + + + + + + + + + diff --git a/notebooks/images/logos/pythia_logo-white-notext.svg b/notebooks/images/logos/pythia_logo-white-notext.svg new file mode 100644 index 0000000..73e2dfe --- /dev/null +++ b/notebooks/images/logos/pythia_logo-white-notext.svg @@ -0,0 +1,128 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/notebooks/images/logos/pythia_logo-white-rtext.svg b/notebooks/images/logos/pythia_logo-white-rtext.svg new file mode 100644 index 0000000..fa2a5c6 --- /dev/null +++ b/notebooks/images/logos/pythia_logo-white-rtext.svg @@ -0,0 +1,225 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/notebooks/landing-page.md b/notebooks/landing-page.md new file mode 100644 index 0000000..31aebd9 --- /dev/null +++ b/notebooks/landing-page.md @@ -0,0 +1,63 @@ +# (Replace_with_your_title) Cookbook + +This Project Pythia Cookbook covers ... (replace `...` with the main subject of your cookbook ... e.g., *working with radar data in Python*) + +## Motivation + +(Add a few sentences stating why this cookbook will be useful. What skills will you, "the chef", gain once you have reached the end of the cookbook?) + +## Structure +(State one or more sections that will comprise the notebook. E.g., *This cookbook is broken up into two main sections - "Foundations" and "Example Workflows."* Then, describe each section below.) + +### Section 1 ( Replace with the title of this section, e.g. "Foundations" ) +(Add content for this section, e.g., "The foundational content includes ... ") + +### Section 2 ( Replace with the title of this section, e.g. "Example workflows" ) +(Add content for this section, e.g., "Example workflows include ... ") + +## Running the Notebooks +You can either run the notebook using [Binder](https://mybinder.org/) or on your local machine. + +### Running on Binder + +The simplest way to interact with a Jupyter Notebook is through +[Binder](https://mybinder.org/), which enables the execution of a +[Jupyter Book](https://jupyterbook.org) in the cloud. The details of how this works are not +important for now. All you need to know is how to launch a Pythia +Cookbooks chapter via Binder. Simply navigate your mouse to +the top right corner of the book chapter you are viewing and click +on the rocket ship icon, (see figure below), and be sure to select +“launch Binder”. After a moment you should be presented with a +notebook that you can interact with. I.e. you’ll be able to execute +and even change the example programs. You’ll see that the code cells +have no output at first, until you execute them by pressing +{kbd}`Shift`\+{kbd}`Enter`. Complete details on how to interact with +a live Jupyter notebook are described in [Getting Started with +Jupyter](https://foundations.projectpythia.org/foundations/getting-started-jupyter.html). + +### Running on Your Own Machine +If you are interested in running this material locally on your computer, you will need to follow this workflow: + +(Replace "cookbook-example" with the title of your cookbooks) + +1. Clone the `https://github.com/ProjectPythiaTutorials/cookbook-example` repository: + + ```bash + git clone https://github.com/ProjectPythiaTutorials/cookbook-example.git + ``` +1. Move into the `cookbook-example` directory + ```bash + cd cookbook-example + ``` +1. Create and activate your conda environment from the `environment.yml` file + ```bash + conda env create -f environment.yml + conda activate cookbook-example + ``` +1. Move into the `notebooks` directory and start up Jupyterlab + ```bash + cd notebooks/ + jupyter lab + ``` + +At this point, you can interact with the notebooks! Make sure to check out the ["Getting Started with Jupyter"](https://foundations.projectpythia.org/foundations/getting-started-jupyter.html) content from the [Pythia Foundations](https://foundations.projectpythia.org/landing-page.html) material if you are new to Jupyter or need a refresher. diff --git a/notebooks/notebook-template.ipynb b/notebooks/notebook-template.ipynb new file mode 100644 index 0000000..b75d86f --- /dev/null +++ b/notebooks/notebook-template.ipynb @@ -0,0 +1,358 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Let's start here! If you can directly link to an image relevant to your notebook, such as [canonical logos](https://github.com/numpy/numpy/blob/main/doc/source/_static/numpylogo.svg), do so here at the top of your notebook. You can do this with Markdown syntax,\n", + "\n", + "> `![](http://link.com/to/image.png \"image alt text\")`\n", + "\n", + "or edit this cell to see raw HTML `img` demonstration. This is preferred if you need to shrink your embedded image. **Either way be sure to include `alt` text for any embedded images to make your content more accessible.**\n", + "\n", + "\"Project" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Project Pythia Notebook Template\n", + "\n", + "Next, title your notebook appropriately with a top-level Markdown header, `#`. Do not use this level header anywhere else in the notebook. Our book build process will use this title in the navbar, table of contents, etc. Keep it short, keep it descriptive. Follow this with a `---` cell to visually distinguish the transition to the prerequisites section." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Overview\n", + "If you have an introductory paragraph, lead with it here! Keep it short and tied to your material, then be sure to continue into the required list of topics below,\n", + "\n", + "1. This is a numbered list of the specific topics\n", + "1. These should map approximately to your main sections of content\n", + "1. Or each second-level, `##`, header in your notebook\n", + "1. Keep the size and scope of your notebook in check\n", + "1. And be sure to let the reader know up front the important concepts they'll be leaving with" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Prerequisites\n", + "This section was inspired by [this template](https://github.com/alan-turing-institute/the-turing-way/blob/master/book/templates/chapter-template/chapter-landing-page.md) of the wonderful [The Turing Way](https://the-turing-way.netlify.app/welcome.html) Jupyter Book.\n", + "\n", + "Following your overview, tell your reader what concepts, packages, or other background information they'll **need** before learning your material. Tie this explicitly with links to other pages here in Foundations or to relevant external resources. Remove this body text, then populate the Markdown table, denoted in this cell with `|` vertical brackets, below, and fill out the information following. In this table, lay out prerequisite concepts by explicitly linking to other Foundations material or external resources, or describe generally helpful concepts.\n", + "\n", + "Label the importance of each concept explicitly as **helpful/necessary**.\n", + "\n", + "| Concepts | Importance | Notes |\n", + "| --- | --- | --- |\n", + "| [Intro to Cartopy](https://foundations.projectpythia.org/core/cartopy/cartopy.html) | Necessary | |\n", + "| [Understanding of NetCDF](https://foundations.projectpythia.org/core/data-formats/netcdf-cf.html) | Helpful | Familiarity with metadata structure |\n", + "| Project management | Helpful | |\n", + "\n", + "- **Time to learn**: estimate in minutes. For a rough idea, use 5 mins per subsection, 10 if longer; add these up for a total. Safer to round up and overestimate.\n", + "- **System requirements**:\n", + " - Populate with any system, version, or non-Python software requirements if necessary\n", + " - Otherwise use the concepts table above and the Imports section below to describe required packages as necessary\n", + " - If no extra requirements, remove the **System requirements** point altogether" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Imports\n", + "Begin your body of content with another `---` divider before continuing into this section, then remove this body text and populate the following code cell with all necessary Python imports **up-front**:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import sys" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Your first content section" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This is where you begin your first section of material, loosely tied to your objectives stated up front. Tie together your notebook as a narrative, with interspersed Markdown text, images, and more as necessary," + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# as well as any and all of your code cells\n", + "print(\"Hello world!\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### A content subsection\n", + "Divide and conquer your objectives with Markdown subsections, which will populate the helpful navbar in Jupyter Lab and here on the Jupyter Book!" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# some subsection code\n", + "new = \"helpful information\"" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Another content subsection\n", + "Keep up the good work! A note, *try to avoid using code comments as narrative*, and instead let them only exist as brief clarifications where necessary." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Your second content section\n", + "Here we can move on to our second objective, and we can demonstrate" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Subsection to the second section\n", + "\n", + "#### a quick demonstration\n", + "\n", + "##### of further and further\n", + "\n", + "###### header levels" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "as well $m = a * t / h$ text! Similarly, you have access to other $\\LaTeX$ equation [**functionality**](https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Typesetting%20Equations.html) via MathJax (demo below from link),\n", + "\n", + "\\begin{align}\n", + "\\dot{x} & = \\sigma(y-x) \\\\\n", + "\\dot{y} & = \\rho x - y - xz \\\\\n", + "\\dot{z} & = -\\beta z + xy\n", + "\\end{align}" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Check out [**any number of helpful Markdown resources**](https://www.markdownguide.org/basic-syntax/) for further customizing your notebooks and the [**Jupyter docs**](https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Working%20With%20Markdown%20Cells.html) for Jupyter-specific formatting information. Don't hesitate to ask questions if you have problems getting it to look *just right*." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Last Section\n", + "\n", + "If you're comfortable, and as we briefly used for our embedded logo up top, you can embed raw html into Jupyter Markdown cells (edit to see):" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "
\n", + "

Info

\n", + " Your relevant information here!\n", + "
" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Feel free to copy this around and edit or play around with yourself. Some other `admonitions` you can put in:" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "
\n", + "

Success

\n", + " We got this done after all!\n", + "
" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "
\n", + "

Warning

\n", + " Be careful!\n", + "
" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "
\n", + "

Danger

\n", + " Scary stuff be here.\n", + "
" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We also suggest checking out Jupyter Book's [brief demonstration](https://jupyterbook.org/content/metadata.html#jupyter-cell-tags) on adding cell tags to your cells in Jupyter Notebook, Lab, or manually. Using these cell tags can allow you to [customize](https://jupyterbook.org/interactive/hiding.html) how your code content is displayed and even [demonstrate errors](https://jupyterbook.org/content/execute.html#dealing-with-code-that-raises-errors) without altogether crashing our loyal army of machines!" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Summary\n", + "Add one final `---` marking the end of your body of content, and then conclude with a brief single paragraph summarizing at a high level the key pieces that were learned and how they tied to your objectives. Look to reiterate what the most important takeaways were.\n", + "\n", + "### What's next?\n", + "Let Jupyter book tie this to the next (sequential) piece of content that people could move on to down below and in the sidebar. However, if this page uniquely enables your reader to tackle other nonsequential concepts throughout this book, or even external content, link to it here!" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Resources and references\n", + "Finally, be rigorous in your citations and references as necessary. Give credit where credit is due. Also, feel free to link to relevant external material, further reading, documentation, etc. Then you're done! Give yourself a quick review, a high five, and send us a pull request. A few final notes:\n", + " - `Kernel > Restart Kernel and Run All Cells...` to confirm that your notebook will cleanly run from start to finish\n", + " - `Kernel > Restart Kernel and Clear All Outputs...` before committing your notebook, our machines will do the heavy lifting\n", + " - Take credit! Provide author contact information if you'd like; if so, consider adding information here at the bottom of your notebook\n", + " - Give credit! Attribute appropriate authorship for referenced code, information, images, etc.\n", + " - Only include what you're legally allowed: **no copyright infringement or plagiarism**\n", + " \n", + "Thank you for your contribution!" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.8" + }, + "nbdime-conflicts": { + "local_diff": [ + { + "diff": [ + { + "diff": [ + { + "key": 0, + "op": "addrange", + "valuelist": [ + "Python 3" + ] + }, + { + "key": 0, + "length": 1, + "op": "removerange" + } + ], + "key": "display_name", + "op": "patch" + } + ], + "key": "kernelspec", + "op": "patch" + } + ], + "remote_diff": [ + { + "diff": [ + { + "diff": [ + { + "key": 0, + "op": "addrange", + "valuelist": [ + "Python3" + ] + }, + { + "key": 0, + "length": 1, + "op": "removerange" + } + ], + "key": "display_name", + "op": "patch" + } + ], + "key": "kernelspec", + "op": "patch" + } + ] + }, + "toc-autonumbering": false + }, + "nbformat": 4, + "nbformat_minor": 4 +}