From e2f8567418eced18865b8593ba1a31b9e0174dcd Mon Sep 17 00:00:00 2001
From: Brian Rose <brose@albany.edu>
Date: Fri, 24 May 2024 13:54:53 -0400
Subject: [PATCH 1/2] Park the cookbook guide in this repo (#426)
* Park the cookbook guide in this repo
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
* Fix sidebar
* Remove checklists
* Fix lists and add button
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
* Improve text on submissions
---------
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
portal/contributing.md | 2 +-
portal/cookbook-guide.md | 96 ++++++++++++++++++++++++++++++++++++++++
portal/index.md | 2 +-
3 files changed, 98 insertions(+), 2 deletions(-)
create mode 100644 portal/cookbook-guide.md
diff --git a/portal/contributing.md b/portal/contributing.md
index 8d94d034..533534e0 100644
--- a/portal/contributing.md
+++ b/portal/contributing.md
@@ -1,4 +1,4 @@
-# Contributor's Guide
+# Project Pythia Contributor's Guide
## Overview
diff --git a/portal/cookbook-guide.md b/portal/cookbook-guide.md
new file mode 100644
index 00000000..4618ccdc
--- /dev/null
+++ b/portal/cookbook-guide.md
@@ -0,0 +1,96 @@
+# 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 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://cookbooks.projectpythia.org).
+
+Before you begin, ask yourself if the content you are developing for a cookbook would be better suited as an addition to an existing cookbook. The best place to discuss cookbook ideas is the [Project Pythia category of the Pangeo Discourse](https://discourse.pangeo.io/c/education/project-pythia/60).
+
+## Data access
+
+Before developing your cookbook, you should consider how it will access the data you plan to use. In loose order of preference, we recommend the following:
+
+1. Rely on data that is already freely available and accessible with tools in the ecosystem. Point to Foundations or other cookbooks for tool how-to guides if needed. Examples include the [CMIP6 Cookbook](https://projectpythia.org/cmip6-cookbook/) and the [CESM LENS on AWS Cookbook](https://projectpythia.org/cesm-lens-aws-cookbook/)
+1. Focus on representative subsets of data that can be packaged alongside the cookbook in-repo. An example is the [Landsat ML Cookbook](https://projectpythia.org/landsat-ml-cookbook/README.html)
+1. Wait for the Pythia team to explore cloud storage support via NSF JetStream or adjacent efforts
+1. Provide the tools and/or clear documentation for accessing the data that you have stored somewhere else
+
+## 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/ProjectPythia/cookbook-template, click "Use this template→Create a new repository"
+1. Give your repository a descriptive name followed by `-cookbook` (e.g., `hydrology-cookbook`, `hpc-cookbook`, `cesm-cookbook`) and a description
+1. Choose "Include all branches" and create the repository. Your browser will be directed to the newly created repository under your GitHub account
+1. Under Settings→Pages, ensure that GitHub Pages is enabled. If it is not, change the Branch from "None" to "gh-pages/(root)" and click "Save"
+1. Under Settings→Actions→General, allow Github Actions to **push** to the repository <img width="901" alt="Screenshot 2023-01-13 at 3 12 47 PM" src="https://user-images.githubusercontent.com/26660300/212428991-cd0ae2f0-73ca-40d8-b983-f122359463aa.png">
+
+Your cookbook is now ready to have content added. In the rest of this guide, we will mostly assume that you are familiar with git/GitHub. If not, we recommend reading through our [GitHub tutorials in Foundations](https://foundations.projectpythia.org/foundations/getting-started-github.html).
+
+## Update repository-specific text
+
+- Automatically adjust link paths that need to be changed from the `cookbook-template` to your new cookbook by manually trigger the action “trigger-replace-links” GitHub action. Do this by navigating to "Actions" -> "trigger-replace-links" -> "Run workflow".
+- Edit `_config.yml`. These will show up on your [card in the gallery](https://cookbooks.projectpythia.org/) and are used for filtering.
+ - title
+ - thumbnail (not logo). You may simply replace the default `thumbnail.png` with your own image
+ - tags
+- Edit the `CITATION.cff` file Change the following fields. These will show up on your [card in the gallery](https://cookbooks.projectpythia.org/) and on your Zenodo citation.
+ - title
+ - authors
+ - authors' ORCID IDs and affiliation websites (optional)
+ - description/abstract
+ - Cookbook contributor name
+- Edit the `notebooks/how-to-cite.md` file with your Cookbook title in the line, "The material in <This Cookbook> is licensed ..."
+
+## Set up the environment
+
+1. [Clone the repository](https://foundations.projectpythia.org/foundations/github/github-cloning-forking.html) in your local workspace
+1. Within `environment.yml`, change `name` from `cookbook-dev` to `<your-cookbook-name>-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 <env-name>`
+1. In `.github/workflows/nightly-build.yaml`, `.github/workflows/publish-book.yaml`, and `.github/workflows/trigger-book-build.yaml`, change the `environment_name` to the name of your environment (ex. `cesm-cookbook-dev`)
+1. If when building your Cookbook in GitHub actions, you get the error, "Exemption Occured: jupyter_client.kernelspec.NoSuchKernel: No such kernel named <environment name>", that means there is an error in your `kernelspec` metadata. You can fix this in the command line by entering in the command line `jupyter nbconvert --to notebook --inplace --Exporter.preprocessors='["nbconvert.preprocessors.ClearMetadataPreprocessor", "nbconvert.preprocessors.ClearOutputPreprocessor"]' notebooks/*.ipynb`
+
+## Develop your cookbook
+
+To add content, you should edit (and duplicate as necessary) the notebook template `notebooks/notebook-template.ipynb`. You can add folders to organize notebooks into sections if applicable.
+Once you have a set of notebooks that you are ready to share, there are various edits that need to be made so that your cookbook is functional and polished. Here is a checklist to go through before moving on to the next step:
+
+- Add the notebooks to `_toc.yml` (the table of contents). See [`radar-cookbook/_toc.yml`](https://github.com/ProjectPythia/radar-cookbook/blob/main/_toc.yml) for syntax
+- Edit `README.md` as described in that file. This is the homepage of your cookbook, so it should be descriptive
+- If your cookbook requires more computing resources than available through GitHub Actions, change `execute_notebooks` from `cache` to `binder` in `_config.yml` to run your cookbook on the Pythia Binder
+- Clear all notebook outputs, since the Pythia infrastructure will execute the notebooks
+- Ensure that your cookbook successfully builds and shows the executed code
+
+## Transfer cookbook to the [ProjectPythia](https://github.com/ProjectPythia) organization
+
+1. [Contact Project Pythia via the Pangeo Discourse](https://discourse.pangeo.io/c/education/project-pythia/60) (or otherwise) to let us know about your cookbook
+1. Someone from the Pythia team will add you as a member of the ProjectPythia organization
+1. Once you have accepted the invitation, navigate to the settings of your cookbook repository, scroll down to the Danger Zone, and click "Transfer"
+1. Select or type "ProjectPythia", confirm, and transfer
+1. Replace the `repository_url` in the `sphinx/config/html_theme_options` of the `_config.yml` file to point to your cookbook's new GitHub repository within the [ProjectPythia](https://github.com/ProjectPythia) organization
+
+You will automatically retain write access to your cookbook, but if you would like to add outside collaborators to the repository, contact a member of the Pythia team to be given the Admin role on your cookbook repository.
+
+You can open issues, PRs, and continue making edits as necessary.
+
+## Make a Zenodo release of your Cookbook
+
+1. On Zenodo toggle on your repository by going to GitHub and then finding your repository. Let a Project Pythia teammember know if you cannot do this.
+1. On GitHub make a new release! This is on the right nav side of the page from your code-view in the repository. Again ask for help if needed. Note Zenodo badge links will fail until you have made a release.
+
+## Add your cookbook to the Cookbooks Gallery!
+
+<span class="d-flex justify-content-center py-4">
+ <a href="https://github.com/ProjectPythia/cookbook-gallery/issues/new?assignees=ProjectPythia%2Feducation&labels=content%2Ccookbook-gallery-submission&template=update-cookbook-gallery.yaml&title=Update+Gallery+with+new+Cookbook" role="button" class="btn btn-light btn-lg" style="display: flex; align-items: center; font-weight: 600; text-decoration: none;">
+ Submit a new Cookbook
+ </a>
+</span>
+
+1. Click the above button, or use this link to the [new cookbook PR template](https://github.com/ProjectPythia/cookbook-gallery/issues/new?assignees=ProjectPythia%2Feducation&labels=content%2Ccookbook-gallery-submission&template=update-cookbook-gallery.yaml&title=Update+Gallery+with+new+Cookbook).
+1. Add the root name of your cookbook repository (e.g., just "cesm-cookbook", not the whole URL) and any other information you'd like the team to know.
+1. The Pythia team will review your content and work with you on any necessary updates.
diff --git a/portal/index.md b/portal/index.md
index 619e2686..df83ff96 100644
--- a/portal/index.md
+++ b/portal/index.md
@@ -224,8 +224,8 @@ maxdepth: 1
---
about.md
contributing.md
+cookbook-guide.md
code_of_conduct.md
-cookbook-gallery.md
resource-gallery.md
metrics.md
```
From 88b494959c0cec1e8cbd5b0bd7aa242faf00cc34 Mon Sep 17 00:00:00 2001
From: Brian Rose <brose@albany.edu>
Date: Fri, 24 May 2024 15:08:47 -0400
Subject: [PATCH 2/2] Point internal links to new guide (#427)
* Point internal links to new guide
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
---------
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
portal/contributing.md | 12 ++++++++++--
1 file changed, 10 insertions(+), 2 deletions(-)
diff --git a/portal/contributing.md b/portal/contributing.md
index 533534e0..7b1cfce8 100644
--- a/portal/contributing.md
+++ b/portal/contributing.md
@@ -1,5 +1,13 @@
# Project Pythia Contributor's Guide
+```{Note}
+This the top-level guide for Project Pythia and a great starting point for getting involved!
+
+We also have specific guides for
+[contributing to Pythia Foundations](https://foundations.projectpythia.org/appendix/how-to-contribute.html)
+and [contributing new Cookbooks](https://projectpythia.org/cookbook-guide.html).
+```
+
## Overview
Welcome! This is the main contributors guide for Project Pythia.
@@ -77,10 +85,10 @@ The Pythia [Cookbook
Gallery](https://cookbooks.projectpythia.org/) is a
collection of "cookbooks" that describe workflows that solve a
specific problem. Typically, a cookbook references material presented
-elsewhere in Project Pythia, such as [Pythia Foundations](https://foundations.projectpythia.org).
+elsewhere in Project Pythia, such as [Pythia Foundations](https://foundations.projectpythia.org).
Each Cookbook is hosted in a separate GitHub repo under the umbrella [Project Pythia
organization](https://github.com/ProjectPythia).
-Contributors should consult the [Cookbook-specific Contributor's guide](https://github.com/ProjectPythia/.github/blob/main/.github/CONTRIBUTING.md).
+Contributors should consult the [Cookbook-specific Contributor's guide](/cookbook-guide).
### Pythia Portal