diff --git a/.github/workflows/build-book.yaml b/.github/workflows/build-book.yaml deleted file mode 100644 index b52f195..0000000 --- a/.github/workflows/build-book.yaml +++ /dev/null @@ -1,76 +0,0 @@ -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 deleted file mode 100644 index 2123ac2..0000000 --- a/.github/workflows/delete-preview.yaml +++ /dev/null @@ -1,26 +0,0 @@ -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.yml b/.github/workflows/deploy-book.yml deleted file mode 100644 index b32b901..0000000 --- a/.github/workflows/deploy-book.yml +++ /dev/null @@ -1,45 +0,0 @@ -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: dawidd6/action-download-artifact@v2.21.1 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - workflow: build-book.yaml - commit: ${{ github.sha }} - 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 deleted file mode 100644 index 538c131..0000000 --- a/.github/workflows/deploy-preview.yaml +++ /dev/null @@ -1,137 +0,0 @@ -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 deleted file mode 100644 index 9ad54c7..0000000 --- a/.github/workflows/link-checker.yaml +++ /dev/null @@ -1,76 +0,0 @@ -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.9.1 - 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 index b5e6aac..8b593f6 100644 --- a/.github/workflows/nightly-build.yaml +++ b/.github/workflows/nightly-build.yaml @@ -7,15 +7,12 @@ on: jobs: build: - uses: ./.github/workflows/build-book.yaml + if: ${{ github.repository_owner == 'ProjectPythiaCookbooks' }} + uses: ProjectPythiaCookbooks/cookbook-actions/.github/workflows/build-book.yaml@main 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/ + if: ${{ github.repository_owner == 'ProjectPythiaCookbooks' }} + uses: ProjectPythiaCookbooks/cookbook-actions/.github/workflows/link-checker.yaml@main + \ No newline at end of file diff --git a/.github/workflows/publish-book.yaml b/.github/workflows/publish-book.yaml new file mode 100644 index 0000000..a8b9e75 --- /dev/null +++ b/.github/workflows/publish-book.yaml @@ -0,0 +1,19 @@ +name: publish-book + +on: + # Trigger the workflow on push to main branch + push: + branches: + - main + workflow_dispatch: + +jobs: + build: + uses: ProjectPythiaCookbooks/cookbook-actions/.github/workflows/build-book.yaml@main + with: + environment_name: cookbook-dev + + deploy: + needs: build + uses: ProjectPythiaCookbooks/cookbook-actions/.github/workflows/deploy-book.yaml@main + \ No newline at end of file diff --git a/.github/workflows/trigger-book-build.yaml b/.github/workflows/trigger-book-build.yaml index c83f56d..b5e4a7f 100644 --- a/.github/workflows/trigger-book-build.yaml +++ b/.github/workflows/trigger-book-build.yaml @@ -4,16 +4,8 @@ on: jobs: build: - uses: ./.github/workflows/build-book.yaml + uses: ProjectPythiaCookbooks/cookbook-actions/.github/workflows/build-book.yaml@main 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' + artifact_name: book-zip-${{ github.event.number }} + # Other input options are possible, see ProjectPythiaCookbooks/cookbook-actions/.github/workflows/build-book.yaml diff --git a/.github/workflows/trigger-delete-preview.yaml b/.github/workflows/trigger-delete-preview.yaml new file mode 100644 index 0000000..d680cde --- /dev/null +++ b/.github/workflows/trigger-delete-preview.yaml @@ -0,0 +1,9 @@ +name: trigger-delete-preview + +on: + pull_request_target: + types: closed + +jobs: + delete: + uses: ProjectPythiaCookbooks/cookbook-actions/.github/workflows/delete-preview.yaml@main diff --git a/.github/workflows/trigger-link-check.yaml b/.github/workflows/trigger-link-check.yaml new file mode 100644 index 0000000..7ea9999 --- /dev/null +++ b/.github/workflows/trigger-link-check.yaml @@ -0,0 +1,8 @@ +name: trigger-link-check +on: + pull_request: + +jobs: + link-check: + uses: ProjectPythiaCookbooks/cookbook-actions/.github/workflows/link-checker.yaml@main + \ No newline at end of file diff --git a/.github/workflows/trigger-preview.yaml b/.github/workflows/trigger-preview.yaml new file mode 100644 index 0000000..1a94e5d --- /dev/null +++ b/.github/workflows/trigger-preview.yaml @@ -0,0 +1,27 @@ +name: trigger-preview +on: + workflow_run: + workflows: + - trigger-book-build + types: + - requested + - completed + +jobs: + find-pull-request: + uses: ProjectPythiaCookbooks/cookbook-actions/.github/workflows/find-pull-request.yaml@main + deploy-preview: + needs: find-pull-request + if: github.event.workflow_run.conclusion == 'success' + uses: ProjectPythiaCookbooks/cookbook-actions/.github/workflows/deploy-book.yaml@main + with: + artifact_name: book-zip-${{ needs.find-pull-request.outputs.number }} + destination_dir: _preview/${{ needs.find-pull-request.outputs.number }} # deploy to subdirectory labeled with PR number + is_preview: 'true' + + preview-comment: + needs: find-pull-request + uses: ProjectPythiaCookbooks/cookbook-actions/.github/workflows/preview-comment.yaml@main + with: + pull_request_number: ${{ needs.find-pull-request.outputs.number }} + sha: ${{ needs.find-pull-request.outputs.sha }} diff --git a/.gitignore b/.gitignore index b6e4761..d449ab3 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,7 @@ __pycache__/ # Distribution / packaging .Python build/ +notebooks/_build/ develop-eggs/ dist/ downloads/ diff --git a/README.md b/README.md index 6840da6..d7732dd 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,76 @@ -# Cookbook Template +thumbnail -This is a template for creating [Project Pythia](https://projectpythia.org) Cookbooks. +# (Replace_with_your_title) Cookbook -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. +[![nightly-build](https://github.com/ProjectPythiaCookbooks/cookbook-template/actions/workflows/nightly-build.yaml/badge.svg)](https://github.com/ProjectPythiaCookbooks/cookbook-template/actions/workflows/nightly-build.yaml) +[![Binder](http://binder.mypythia.org/badge_logo.svg)](http://binder.mypythia.org/v2/gh/ProjectPythiaCookbooks/cookbook-template/main?labpath=notebooks) -You can use the `notebook-template` in `/notebooks` as your content template! +This Project Pythia Cookbook covers ... (replace `...` with the main subject of your cookbook ... e.g., *working with radar data in Python*) -Once you have made your new content, add it to the table of contents (`notebooks/_toc.yml`) file, and push it to Github! +## 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?) + +## Authors + +[First Author](@first-author), [Second Author](@second-author), etc. *Acknowledge primary content authors here* + +### Contributors + + + + + +## 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/ProjectPythiaCookbooks/cookbook-example` repository: + + ```bash + git clone https://github.com/ProjectPythiaCookbooks/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 + ``` diff --git a/notebooks/_config.yml b/_config.yml similarity index 69% rename from notebooks/_config.yml rename to _config.yml index ef206ab..f425e8c 100644 --- a/notebooks/_config.yml +++ b/_config.yml @@ -1,15 +1,25 @@ # Book settings # Learn more at https://jupyterbook.org/customize/config.html -title: Pythia Foundations +title: Project Pythia Test Cookbook author: the Project Pythia Community -logo: images/logos/pythia_logo-white-rtext.svg +logo: notebooks/images/logos/pythia_logo-white-rtext.svg email: projectpythia@ucar.edu copyright: '2022' -# Don't execute the notebooks upon building the book +description: A sample cookbook description. +thumbnail: thumbnail.png +tags: + domains: + - sampledomain + packages: + - samplepackage + execute: - execute_notebooks: "off" + # To execute notebooks via a binder instead, replace 'cache' with 'binder' + execute_notebooks: cache + timeout: 600 + allow_errors: True # Add a few extensions to help with parsing content parse: @@ -32,12 +42,13 @@ sphinx: 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_url: https://github.com/ProjectPythiaCookbooks/test-cookbook/ # 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 + google_analytics_id: G-T52X8HNYE8 + github_url: https://github.com/ProjectPythiaCookbooks twitter_url: https://twitter.com/project_pythia icon_links: - name: YouTube @@ -45,7 +56,7 @@ sphinx: icon: fab fa-youtube-square type: fontawesome launch_buttons: - binderhub_url: https://mybinder.org + binderhub_url: http://binder.mypythia.org notebook_interface: jupyterlab extra_navbar: | Theme by Project Pythia.

@@ -57,12 +68,12 @@ sphinx: - name: Foundations url: https://foundations.projectpythia.org - name: Cookbooks - url: projectpythiatutorials.github.io + url: https://cookbooks.projectpythia.org - 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 + NCAR: notebooks/images/logos/NCAR-contemp-logo-blue.svg + Unidata: notebooks/images/logos/Unidata_logo_horizontal_1200x300.svg + UAlbany: notebooks/images/logos/UAlbany-A2-logo-purple-gold.svg \ No newline at end of file diff --git a/notebooks/_toc.yml b/_toc.yml similarity index 53% rename from notebooks/_toc.yml rename to _toc.yml index 1319fc1..2fed654 100644 --- a/notebooks/_toc.yml +++ b/_toc.yml @@ -1,6 +1,6 @@ format: jb-book -root: landing-page +root: README parts: - caption: Introduction chapters: - - file: notebook-template + - file: notebooks/notebook-template diff --git a/environment.yml b/environment.yml index 49fe2c2..c853231 100644 --- a/environment.yml +++ b/environment.yml @@ -3,6 +3,7 @@ channels: - conda-forge dependencies: - jupyter-book + - jupyterlab - pip - pip: - sphinx-pythia-theme diff --git a/notebooks/landing-page.md b/notebooks/landing-page.md deleted file mode 100644 index 312f968..0000000 --- a/notebooks/landing-page.md +++ /dev/null @@ -1,3 +0,0 @@ -# Cookbook Overview - -This is the the landing page for your cookbook - update as neccessary! diff --git a/thumbnail.png b/thumbnail.png new file mode 100644 index 0000000..8d49fc2 Binary files /dev/null and b/thumbnail.png differ diff --git a/thumbnail.svg b/thumbnail.svg new file mode 100644 index 0000000..c8d0ab1 --- /dev/null +++ b/thumbnail.svg @@ -0,0 +1 @@ +