From 10d256d9e12c55447b21a25a45153ec6a203e4f6 Mon Sep 17 00:00:00 2001 From: Christian-Kofi-Okyere Date: Wed, 25 Jun 2025 10:06:23 -0600 Subject: [PATCH 1/2] Made a quicker cookbook guide. Referenced back the original guide. --- portal/cookbook-guide.md | 8 +++++ portal/quick-cookbook-guide.md | 62 ++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 portal/quick-cookbook-guide.md diff --git a/portal/cookbook-guide.md b/portal/cookbook-guide.md index 487c42b09..b87de17d8 100644 --- a/portal/cookbook-guide.md +++ b/portal/cookbook-guide.md @@ -1,5 +1,13 @@ # Cookbook Contributor's Guide + +

+ + ← Back to Quickstart 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 diff --git a/portal/quick-cookbook-guide.md b/portal/quick-cookbook-guide.md new file mode 100644 index 000000000..2fe9ce276 --- /dev/null +++ b/portal/quick-cookbook-guide.md @@ -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** +

+ + Full Cookbook Contributor's Guide → + +

+ + +--- +## Create Repository Using Template + +1. Navigate to [projectpythia-mystmd/cookbook-template](https://github.com/projectpythia-mystmd/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 → Binder → 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-mystmd` organization +2. From **repository settings**, transfer the repo to the `projectpythia-mystmd` 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** From 49282fef376fe21ca1c922f5cc552074f5a4dd20 Mon Sep 17 00:00:00 2001 From: Christian-Kofi-Okyere Date: Wed, 25 Jun 2025 12:10:35 -0600 Subject: [PATCH 2/2] Added the quick guide --- myst.yml | 1 + portal/cookbook-guide.md | 14 +------------- portal/quick-cookbook-guide.md | 6 +++--- 3 files changed, 5 insertions(+), 16 deletions(-) diff --git a/myst.yml b/myst.yml index 348139311..4d26878cc 100644 --- a/myst.yml +++ b/myst.yml @@ -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 diff --git a/portal/cookbook-guide.md b/portal/cookbook-guide.md index b87de17d8..9701a8252 100644 --- a/portal/cookbook-guide.md +++ b/portal/cookbook-guide.md @@ -9,7 +9,7 @@ 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. @@ -84,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" → "trigger-replace-links" → "Run workflow". ## Set up the computational environment @@ -98,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 (`-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 `-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 diff --git a/portal/quick-cookbook-guide.md b/portal/quick-cookbook-guide.md index 2fe9ce276..0d8a61a71 100644 --- a/portal/quick-cookbook-guide.md +++ b/portal/quick-cookbook-guide.md @@ -11,7 +11,7 @@ For a more detailed, step-by-step contributor guide, see the **Full Cookbook Con --- ## Create Repository Using Template -1. Navigate to [projectpythia-mystmd/cookbook-template](https://github.com/projectpythia-mystmd/cookbook-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: @@ -55,8 +55,8 @@ Follow [Git/GitHub best practices](https://foundations.projectpythia.org/foundat ## Ready to Publish? -1. Make sure you’re added to the `projectpythia-mystmd` organization -2. From **repository settings**, transfer the repo to the `projectpythia-mystmd` organization +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**