Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions myst.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ project:
- pattern: portal/posts/*.md
- file: portal/contributing.md
- file: portal/cookbook-guide.md
- file: portal/quick-cookbook-guide.md
- file: portal/metrics.md
site:
template: book-theme
Expand Down
22 changes: 9 additions & 13 deletions portal/cookbook-guide.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,15 @@
# Cookbook Contributor's Guide


<p style="text-align: center; margin-top: 2em;">
<a href="quick-cookbook-guide.md" style="display: inline-block; background-color:rgb(13, 83, 130); color: white; padding: 8px 10px; font-size: 1.1em; border-radius: 8px;">
&leftarrow; Back to Quickstart Guide
</a>
</p>


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).
workflows building on top of [Pythia Foundations](https://foundations.projectpythia.org/).
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.
Expand Down Expand Up @@ -76,7 +84,6 @@ Once you have successfully transfered the repository, you'll most likely want to

Whether the repository lives in your personal GitHub space or on the ProjectPythia organization, there are several paths and links in the repository code that need to be updated to reflect the current home of your cookbook source. This step is necessary to ensure that the cookbook building and publishing infrastructure works as intended.

Fortunately this is quick and easy. Just run our custom GitHub action called `trigger-replace-links`: Navigate to "Actions" &rarr; "trigger-replace-links" &rarr; "Run workflow".

## Set up the computational environment

Expand All @@ -90,18 +97,7 @@ You'll most likely want to do your edits in a [local clone of the repository](ht

You're now ready to create and run awesome notebooks.

### Customizing your GitHub actions

Your repository includes automation for building and publishing your Cookbook, powered by [GitHub Actions](https://docs.github.com/en/actions). Now that you have created a custom name for your conda environment (`<your-cookbook-name>-dev`), you need to edit three files found in the `.github/workflows` section of your repo:
- `.github/workflows/nightly-build.yaml`
- `.github/workflows/publish-book.yaml`
- `.github/workflows/trigger-book-build.yaml`

In each of these files, in the field called `environment_name:`, replace `cookbook-dev` with the name you used in your `environment.yml` file (probably `<your-cookbook-name>-dev`). Commit these changes.

```{note}
If these workflow files look mysterious and you don't know anything about how GitHub Actions work, don't worry! The Pythia team will help with any problems that arise with the Cookbook automation.
```

## Develop your cookbook

Expand Down
62 changes: 62 additions & 0 deletions portal/quick-cookbook-guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# MyST Cookbook Contributing Guide Notes

For a more detailed, step-by-step contributor guide, see the **Full Cookbook Contributor's Guide**
<p style="text-align: center; margin-top: 2em;">
<a href="cookbook-guide.md" style="display: inline-block; background-color:rgb(13, 83, 130); color: white; padding: 8px 10px; font-size: 1.1em; border-radius: 8px;">
Full Cookbook Contributor's Guide &rightarrow;
</a>
</p>


---
## Create Repository Using Template

1. Navigate to [projectpythia/cookbook-template](https://github.com/projectpythia/cookbook-template)
2. Click **"Use This Template"** → **"Create a new repository"**

### On the next page:
- Check **"Include all branches"**
- You are the **owner**
- Create your repository name (should end with `-cookbook`)
- Select to keep it **Public**
- Then click **"Create repository"**


---

## Update Content

Follow [Git/GitHub best practices](https://foundations.projectpythia.org/foundations/getting-started-github.html) with your collaborators:

- Add content with your scientific insight as `.ipynb` files in the `notebooks/` folder
- Update `environment.yml` to include all necessary packages
- Update **thumbnail** to visually represent your work
- Update `README.md` to reflect:
- Title
- Description
- Motivation
- Authors
- Content structure

- Update `myst.yml` with:
- Title
- GitHub link
- Tags
- Keywords (clarify the difference!)
- Table of contents (`toc`)
- Jupyter &rarr; Binder &rarr; Repo links

- Update `CITATION.cff` with:
- Authors’ names, ORCID, website, and affiliation
- Title
- Abstract

---

## Ready to Publish?

1. Make sure you’re added to the `ProjectPythia` organization
2. From **repository settings**, transfer the repo to the `ProjectPythia` organization
3. Open a PR editing `cookbook_gallery.txt` with your repo name in the [Cookbook Gallery Repository](https://github.com/projectpythia/cookbook-gallery)
4. Await review
5. Someone from the Pythia team will publish a **citable release**