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. They are geoscience-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.

1. Use the template
   1. If you don't already have a GitHub account, create one by following the Getting Started with GitHub guide
   2. On https://github.com/ProjectPythiaCookbooks/cookbook-template, click "Use this template"
   3. Choose "Include all branches"
   4. 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"
   5. 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"
   6. Clone the repo in your local workspace and cd into your cookbook directory
2. Create the environment
   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
   2. Create the Conda environment with conda env create -f environment.yml. If it crashes, try running conda config --set channel_priority strict
   3. Activate your environment with conda activate <env-name>
3. Add content
   1. After creating a new git branch, 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
   2. Add the notebooks to _toc.yml. See radar-cookbook/_toc.yml for syntax
   3. Replace the thumbnail.svg with a thumbnail image relevant to your cookbook
   4. Change README.md to include your cookbook title, a sentence or two describing the cookbook, and if desired embed your thumbnail image. See the Radar Cookbook for an example
   5. In the badge links in README.md, change cookbook-template to your cookbook repo name.
   6. Commit your changes with git, and open a Pull Request on your cookbook repo. When you open a PR there, the github-actions bot will comment a link to a preview of your cookbook
4. Transfer cookbook to the ProjectPythiaCookbooks organization
   1. Navigate to the settings of your repo, scroll down to the Danger Zone, and click "Transfer"
      1. For ProjectPythiaCookbooks owners or members: type "ProjectPythiaCookbooks", confirm, and transfer.
      2. For outside contributors:
         1. Contact an owner of ProjectPythiaCookbooks to be added as an outside collaborator. Then transfer to ProjectPythiaCookbooks; or
         2. Type the username of an owner or member. They will then tranfer it to ProjectPythiaCookbooks and add you as an outside collaborator on that repo
   2. Open issues, PRs, and continue making edits as necessary