diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cc66c1bb..7d3ed142 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,7 @@ -# Pythia Portal contributor's guide +# Contributing to the Project Pythia Portal This document contains information specific to contributing to the -Project Pythia Portal. Please first refer to [Pythia Contributor's -Guide](https://projectpythia.org/contributing.html) for overall +Project Pythia Portal. Please first refer to [Guide for Contributing to Project Pythia](https://projectpythia.org/contributing.html) for overall contribution guidelines (such as detailed description of Project Pythia structure, forking, repository cloning, branching, etc.). @@ -22,7 +21,7 @@ The post will automatically be recognized and displayed when you build the porta ## Instructions for building the portal site -The portal site is built with [Sphinx](https://www.sphinx-doc.org/). +The portal site is built with [MyST-MD](https://mystmd.org/). When testing new content it is important to build and view the site. Read the Docs automatically builds the site for you when each Pull Request is checked. However, you can also build it locally on your machine following the instructions below. @@ -70,28 +69,12 @@ _NOTE_: The `pre-commit` package is already installed via the `pythia` conda env Build the site locally using Sphinx (which you just installed in the `pythia` environment, along with all necessary dependencies): ```bash -make html +myst start --execute ``` -If this step fails and you have not updated your conda environment recently, try updating with `conda env update -f ../environment.yml` and `conda update --all` as described above. +If this step fails and you may not have updated your conda environment recently, try updating with `conda env update -f ../environment.yml` and `conda update --all` as described above. -The newly rendered site is now available in `portal/_build/html/index.html`. -Open with your web browser, or from the terminal: - -```bash -open _build/html/index.html -````` - -However, many of the links will not work. For all of the links -found in the portal to work properly, you'll need to set up a local -testing server. This can be done with Python's http.server by running -the following command from within the `portal` directory: - -```bash -python -m http.server --directory _build/html/ -``` - -and then pointing your browser at the URL: localhost:8000. +The newly rendered site is now available at [localhost:3000](http://localhost:3000). A link should appear in your terminal. More information on setting up a local test server is available from [here](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/set_up_a_local_testing_server) @@ -108,15 +91,6 @@ conda activate pythia conda update --all ``` -### Preview the built site on Netlify - -Once a pull request has passed all tests, including the `preview-site` check, the GitHub bot will post a comment with a preview link on the pull request. You can click on the link to launch a new tab with a build of the Project Pythia site. - -![CI-check](/portal/_static/images/deploy-site-CI-check.png) - -![Netlify Preview](/portal/_static/images/netlify-preview.png) - - ## Instructions for intacting with the Google Analytics API ### Setting up the Virtual Environment diff --git a/myst.yml b/myst.yml new file mode 100644 index 00000000..79c700bc --- /dev/null +++ b/myst.yml @@ -0,0 +1,30 @@ +# See docs at: https://mystmd.org/guide/frontmatter +version: 1 +extends: + - https://raw.githubusercontent.com/projectpythia/pythia-config/main/pythia.yml +project: + id: 770e49e5-344a-4c46-adaa-3afb060b2085 + # title: + # description: + keywords: [] + authors: [] + github: https://github.com/projectpythia/projectpythia.github.io + # bibliography: [] + + toc: + - file: portal/index.md + - file: portal/about.md + - title: Blog + children: + - pattern: portal/posts/*.md + - file: portal/contributing.md + - file: portal/cookbook-guide.md + - file: portal/quick-cookbook-guide.md + - file: portal/metrics.md +site: + actions: + - title: Learn More + url: https://mystmd.org/guide + domains: [] + options: + style: style.css diff --git a/portal/contributing.md b/portal/contributing.md index 09a0baf5..1cffc928 100644 --- a/portal/contributing.md +++ b/portal/contributing.md @@ -1,4 +1,4 @@ -# Project Pythia Contributor's Guide +# Contributing to Project Pythia ```{note} This the top-level guide for Project Pythia and a great starting point for getting involved! @@ -10,7 +10,7 @@ and [contributing new Cookbooks](https://projectpythia.org/cookbook-guide.html). ## Overview -Welcome! This is the main contributors guide for Project Pythia. +Welcome! This is the main guide for contributing to Project Pythia. Project Pythia is an open community, and all contributions are welcome following our [Code of Conduct](https://projectpythia.org/code_of_conduct.html). All @@ -18,8 +18,7 @@ of the content for Project Pythia is hosted on GitHub in a number of different public repositories. From this document you can learn about the many ways that you can contribute to this community project, and where you can find additional information. In many -cases pertinent details may be found in repository-specific -contributors guides **that should always be consulted in addition +cases pertinent details may be found in repository-specific guides **that should always be consulted in addition to this guide**. More on this topic later. ## The many ways to contribute @@ -72,7 +71,7 @@ is a collection of material that the Pythia team believes is essential knowledge for geoscientists to effectively use the Scientific Python Ecosystem. The Pythia Foundations content is hosted on a separate [GitHub repo](https://github.com/ProjectPythia/pythia-foundations), -and contributors should consult the contributor’s guide there for +and contributors should consult the [Contributing to Foundations](https://foundations.projectpythia.org/appendix/how-to-contribute) guide there for information specific to Foundations. However, adding new, or changing existing Foundations content requires contributors to be familiar with a few technologies and workflows, described in Advanced @@ -88,7 +87,7 @@ specific problem. Typically, a cookbook references material presented 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](/cookbook-guide). +Contributors should consult the [Contributing a New Cookbook](/cookbook-guide) guide. ### Pythia Portal @@ -114,10 +113,10 @@ process of setting up GitHub/Git, installing and configuring conda, and submitting a PR. Note, while this information is common to all Pythia repositories, repo-specific information might be required. -In all cases contributors should consult the repo-specific contributor’s +In all cases contributors should consult the repo-specific contribution guide for their target repository. -Repo-specific guides can be found in the file named `CONTRIBUTING.md`, located in the top level directory of each repository, or by clicking on the menu item labeled “Contributor’s Guide” found in the rendered content generated by each repository. +Repo-specific guides can be found in the file named `CONTRIBUTING.md`, located in the top level directory of most repositories, or by clicking on the appropriately named menu item on each site. Note that the "Contributing a new Cookbook" guide is found in the Pythia portal (rather than in any one specific Cookbook). Lastly, much of this information has been co-opted from the [GeoCAT project](https://geocat.ucar.edu). @@ -221,12 +220,12 @@ desktop or laptop. Before using your conda environment to work on Pythia content, you'll need to perform an addtional one-time setup that is specific to each Pythia repo. After the one-time configuration is complete you will need to "activate" a repo-specific environment whenever -you wish to use it. Consult the repo-specific contributor’s guide +you wish to use it. Consult the repo-specific contribution guide for information on “Building the site”, and follow the steps described therein. ```{note} -Repository-specific contributor's +Repository-specific contribution information can always be accessed by navigating your web browser to the appropriate Project Pythia GitHub repository, [here](https://github.com/ProjectPythia/pythia-foundations) for @@ -337,7 +336,7 @@ back to the Pythia repository you will need to submit a Pull Request ### Make your local changes At this point you should be able to make your desired changes to -the local copies of your files. **Always consult the repo-specific contributor’s +the local copies of your files. **Always consult the repo-specific contribution guide for information specific to the repo you are working on.** ### Submit a Pull Request (PR) diff --git a/portal/cookbook-guide.md b/portal/cookbook-guide.md index 2b9018ba..86422c88 100644 --- a/portal/cookbook-guide.md +++ b/portal/cookbook-guide.md @@ -1,7 +1,13 @@ -# Cookbook Contributor's Guide +# Contributing a New Cookbook + +

+ + ← 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). +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. @@ -18,7 +24,7 @@ Using the Pythia Cookbook template to create reproducible documents housed elsew If you're not looking to create a _new_ Cookbook, but rather looking for guidance on contributing to _existing_ Cookbooks, first make sure you're comfortable with the [GitHub forking workflow](https://foundations.projectpythia.org/foundations/github/github-workflows.html#forking-workflow), then take a look at the section below on "Pull Requests and previews". -## Data access +## A. 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: @@ -27,62 +33,30 @@ Before developing your cookbook, you should consider how it will access the data 1. Discuss your larger data storage needs with the Pythia team. We are currently experimenting with cloud object storage for Cookbooks via NSF JetStream2. 1. Provide the tools and/or clear documentation for accessing the data that you have stored somewhere else -## Use the template +## B. Create a Repository From the Cookbook 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 the [Cookbook Template repository](https://github.com/ProjectPythia/cookbook-template), click "Use this template → Create a new repository" +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 the [Cookbook Template repository](https://github.com/ProjectPythia/cookbook-template), click "Use this template → Create a new repository". 1. Choose "Include all branches". -1. Give your repository a descriptive name followed by `-cookbook` (e.g., `hydrology-cookbook`, `hpc-cookbook`, `cesm-cookbook`) and a description -1. 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 by checking that `Branch` is set to "gh-pages", and the folder set to "gh-pages/(root)". If it is not, change the Branch from "None" to "gh-pages/(root)" and click "Save" -1. Under Settings → Actions → General, make sure that "Read and write permissions" is selected. Screenshot 2023-01-13 at 3 12 47 PM +1. Give your repository a descriptive name followed by `-cookbook` (e.g., `hydrology-cookbook`, `hpc-cookbook`, `cesm-cookbook`) and a description. +1. 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 by checking that `Branch` is set to "gh-pages", and the folder set to "gh-pages/(root)". If it is not, change the Branch from "None" to "gh-pages/(root)" and click "Save". +1. Under Settings → Actions → General, make sure that "Read and write permissions" is selected. -Your cookbook is now ready to have content added! +Screenshot 2023-01-13 at 3 12 47 PM ```{note} In the rest of this guide, we assume that you are familiar with the basics of using git and GitHub. If not, we strongly recommend reading through our [GitHub tutorials in Foundations](https://foundations.projectpythia.org/foundations/getting-started-github.html). ``` -## Transfer your cookbook repo to the ProjectPythia organization - -In order for your Cookbook to be included in the Gallery, the source repository needs to be housed within the [Project Pythia GitHub organization](https://github.com/ProjectPythia). - -You can keep your repository in your personal GitHub space while you're developing your content if that works better for you. Repository ownership can be transferred at any time. - -However, we recommend transferring to the Pythia organization early, for a few reasons: -- Fewer settings to tweak later -- Easier to get help from the Pythia infrastructure team -- Encourages collaboration - -```{note} -You're still in control! You will always retain write access to your Cookbook repository even after transfering ownership to the Pythia organization. - -Also, _don't worry about breaking anything!_ Your repo will not affect any other Project Pythia content until you initiate the request to list it on the [Cookbook Gallery](https://cookbooks.projectpythia.org) (see below...) -``` - -### Steps to transfer the repository - -1. [Contact the Pythia team via the Pangeo Discourse](https://discourse.pangeo.io/c/education/project-pythia/60) (or otherwise) to let us know about your cookbook. -1. You will get an invitation to join the [ProjectPythia organization](https://github.com/ProjectPythia). -1. Accept the GitHub invitation. _Welcome to the team!_ -1. Once you are a member of the organization, navigate to the Settings of your cookbook repository and scroll down to the **Danger Zone**. -1. Click "Transfer". -1. Select or type "ProjectPythia", confirm, and transfer. -1. When prompted about which teams to give access to, select "core". _This will enable the Pythia maintenance team to have full access to your repository._ - -Once you have successfully transferred the repository, you'll most likely want to make a [personal fork and a local clone of the repository](https://foundations.projectpythia.org/foundations/github/github-cloning-forking.html) so that you can continue to develop and collaborate on the Cookbook via the [forking workflow](https://foundations.projectpythia.org/foundations/github/github-workflows.html#forking-workflow). - -## Customize the paths in your repository - -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. +Your cookbook is now ready to have content added! -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 +## C. Set up the Computational Environment You'll most likely want to do your edits in a [local clone of the repository](https://foundations.projectpythia.org/foundations/github/github-cloning-forking.html) on your laptop or wherever your are running your notebooks. -### Customizing your environment file +### Customizing Your Conda Environment 1. Within `environment.yml` (in the root of the repository), change `name` from `cookbook-dev` to `-dev` (e.g. `cesm-cookbook-dev`) and add all required libraries and other dependencies under `dependencies:`. Commit the changes. 1. Create the [conda environment](https://foundations.projectpythia.org/foundations/conda.html) with `conda env create -f environment.yml`. If it crashes, try running `conda config --set channel_priority strict` @@ -90,45 +64,47 @@ 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` +## D. Develop your Cookbook -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. +### 1. Add Notebooks -```{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. -``` +To add content, you should edit (and duplicate as necessary) the notebook template `notebooks/notebook-template.ipynb`. Using this template will help keep your content consistent with the expected Cookbook style. -## Develop your cookbook +### 2. Update Your Configuration File -### Add notebooks +The organization of your notebooks within the published book is dictated by the table of contents level of the `myst.yml` configuration file. _Edit this file to add your chapters / subfolders._ -To add content, you should edit (and duplicate as necessary) the notebook template `notebooks/notebook-template.ipynb`. Using this template will help keep your content consistent with the expected Cookbook style. +Required changes to your `myst.yml` file are all under the `project` section. Update the values for these fields: +- `title` +- `github` +- `authors` +- `toc` (table of contents) +- `Jupyter -> Binder -> Repo` -You can add subfolders to organize your notebook files as necessary. However, the organization of the notebooks within the published book is dictated by the table of contents file `_toc.yml`. _Edit this file to add your chapters._ Take a look at the [`radar-cookbook/_toc.yml`](https://github.com/ProjectPythia/radar-cookbook/blob/main/_toc.yml) for example syntax, or consult the [JupyterBook documentation](https://jupyterbook.org/en/stable/structure/toc.html). +Take a look at the [`radar-cookbook/myst.yml`](https://github.com/ProjectPythia/radar-cookbook/blob/main/_toc.yml) for example syntax. -### Customize your home page +### 3. Customize Your Home Page -The file `README.md` serves as the homepage of your Cookbook, so it should be descriptive. Edit this file as appropriate, following guidance in the file itself. +The file `README.md` serves as the homepage of your Cookbook, so it should be descriptive. Edit this file as appropriate, following guidance in the file itself. Make sure this file represents your new: +- Title +- Description +- Motivation +- Authors +- Content structure +- The paths in the nightly build, Binder, and DOI badges. -### Build your Cookbook locally +### 4. Build Your Cookbook Locally You should be able to build your new Cookbook on your local machine by running this command from the root of the repository: ``` -jupyter-book build . +myst start --execute ``` -from the root of your repository. This will execute all your notebooks and package them into a book styled with the Pythia theme. +from the root of your repository. This will execute all your notebooks. + +If the build is successful, you should be able to preview the result in a web browser at [localhost:3000](http://localhost:3000) -If the build is successful, you should be able to preview the result in a web browser by running -``` -open _build/html/index.html -``` -### Strip output from your notebooks before committing +### 5. Strip Output From Your Notebooks Before Committing Wherever feasible, we recommend only committing bare, unexecuted notebooks into your Cookbook repository. There are a few reasons: - The notebooks are executed automatically each time the book is built @@ -140,7 +116,67 @@ To strip a notebook, in a Jupyter Lab session, go to "Kernel" → "Restart Ke You're ready to push content up to GitHub and trigger the automated publishing pipeline. -## Deploying your Cookbook +## E. Making Your Cookbook Findable and Citable + +### 1. Credit yourself + +Cookbooks are scholarly objects. As part of the publication process, your Cookbook will get a citable DOI (via [Zenodo](https://zenodo.org)). Just as for journal publications, you need to make decisions about who gets credited for authorship. + +This information is managed manually through the file `CITATION.cff` in the root of your repository. This will determine the names displayed on your card in the [gallery](https://cookbooks.projectpythia.org/) as well as your DOI-based citation. + +Edit `CITATION.cff` as follows: + +- If you haven't already, _remove the people already listed in this file_. These are the credited authors of the [Cookbook Template](https://github.com/ProjectPythia/cookbook-template) only, and they should not be included in your author list (unless one of them also happens to be a content author for your book). +- Set your Cookbook title +- Write a short description / abstract (this will also appear on the [gallery](https://cookbooks.projectpythia.org/)) +- Include names of all content authors + - ORCID and other metadata for each author is optional but helpful +- Under the `name:` field, change "Cookbook Template contributors" to "[Your Cookbook Name] contributors" + +```{note} +GitHub automatically tracks all contributions to your repository. The folks who help with infrastructure fixes, content reviews, etc., are considered "contributors" but not primary authors. We include the "contributors" as a single group in `CITATION.cff` to acknowledge this! +``` + +### 2. Tag your Cookbook + +The file `_gallery_info.yml` determines how your Cookbook will be findable on the [gallery](https://cookbooks.projectpythia.org/). Edit this file with the following: + +- Replace `thumbnail.png` with your own image (which will appear on your gallery card) +- Edit the tags under `domains` and `packages` as appropriate. Check out the existing filters on the [gallery page](https://cookbooks.projectpythia.org/) to get a sense of how these are used. + + + +## F. Transfer Your Cookbook to the ProjectPythia Organization + +In order for your Cookbook to be included in the Gallery, the source repository needs to be housed within the [Project Pythia GitHub organization](https://github.com/ProjectPythia). + +You can keep your repository in your personal GitHub space while you're developing your content if that works better for you. Repository ownership can be transferred at any time. + +However, we recommend transferring to the Pythia organization early, for a few reasons: +- Fewer settings to tweak later +- Easier to get help from the Pythia infrastructure team +- Encourages collaboration + +```{note} +You're still in control! You will always retain write access to your Cookbook repository even after transfering ownership to the Pythia organization. + +Also, _don't worry about breaking anything!_ Your repo will not affect any other Project Pythia content until you initiate the request to list it on the [Cookbook Gallery](https://cookbooks.projectpythia.org) (see below...) +``` + +### Steps to Transfer the Repository + +1. [Contact the Pythia team via the Pangeo Discourse](https://discourse.pangeo.io/c/education/project-pythia/60) (or otherwise) to let us know about your cookbook. +1. You will get an invitation to join the [ProjectPythia organization](https://github.com/ProjectPythia). +1. Accept the GitHub invitation. _Welcome to the team!_ +1. Once you are a member of the organization, navigate to the Settings of your cookbook repository and scroll down to the **Danger Zone**. +1. Click "Transfer". +1. Select or type "ProjectPythia", confirm, and transfer. +1. When prompted about which teams to give access to, select "core". _This will enable the Pythia maintenance team to have full access to your repository._ + +Once you have successfully transferred the repository, you'll most likely want to make a [personal fork and a local clone of the repository](https://foundations.projectpythia.org/foundations/github/github-cloning-forking.html) so that you can continue to develop and collaborate on the Cookbook via the [forking workflow](https://foundations.projectpythia.org/foundations/github/github-workflows.html#forking-workflow). + + +## G. Deploying your Cookbook Pythia Cookbooks are not just collections of notebooks! They are backed by GitHub-based automation that handles building, testing, previewing, and publishing the books online. @@ -204,47 +240,9 @@ Here's how: The Binder uses your `environment.yml` file to create an image of an execution environment, which is stored for reuse. The time to execute your notebooks can vary, depending on whether the Binder needs to build a new image or not. ``` -## Publish your Cookbook on the Pythia Gallery - -Once you're happy with your content and your Cookbook is building and deploying properly, it's time to think about submitting it for inclusion in the [Cookbook Gallery](https://cookbooks.projectpythia.org/)! - -```{note} -Cookbooks don't need to be "finished" in order to accepted in the Gallery! Cookbooks are typically accepted so long as they run cleanly, are free of obvious errors, and have some relevant new content. - -Cookbooks are meant to be living documents. We encourage authors to open GitHub issues to track progress on adding and updating content. -``` - -At this stage, there are a few more steps to get things ready to go. - -### Authorship and the `CITATION.cff` file - -Cookbooks are scholarly objects. As part of the publication process, your Cookbook will get a citable DOI (via [Zenodo](https://zenodo.org)). Just as for journal publications, you need to make decisions about who gets credited for authorship. - -This information is managed manually through the file `CITATION.cff` in the root of your repository. This will determine the names displayed on your card in the [gallery](https://cookbooks.projectpythia.org/) as well as your DOI-based citation. - -Edit `CITATION.cff` as follows: - -- If you haven't already, _remove the people already listed in this file_. These are the credited authors of the [Cookbook Template](https://github.com/ProjectPythia/cookbook-template) only, and they should not be included in your author list (unless one of them also happens to be a content author for your book). -- Set your Cookbook title -- Write a short description / abstract (this will also appear on the [gallery](https://cookbooks.projectpythia.org/)) -- Include names of all content authors - - ORCID and other metadata for each author is optional but helpful -- Under the `name:` field, change "Cookbook Template contributors" to "[Your Cookbook Name] contributors" - -```{note} -GitHub automatically tracks all contributions to your repository. The folks who help with infrastructure fixes, content reviews, etc., are considered "contributors" but not primary authors. We include the "contributors" as a single group in `CITATION.cff` to acknowledge this! -``` - -### Gallery tags - -The file `_gallery_info.yml` determines how your Cookbook will be findable on the [gallery](https://cookbooks.projectpythia.org/). Edit this file with the following: - -- Replace `thumbnail.png` with your own image (which will appear on your gallery card) -- Edit the tags under `domains` and `packages` as appropriate. Check out the existing filters on the [gallery page](https://cookbooks.projectpythia.org/) to get a sense of how these are used. - -### Generate a DOI +## H. Release a Version of Your Cookbook -Once all the above steps are complete and your `CITATION.cff` file is correct, you are ready to "release" a tagged version of your book and generate your first DOI. We've tried to make this as painless as possible, but there are a few more steps to take initially. +Once all the above steps are complete and your `CITATION.cff` file is correct, you are ready to "release" a tagged version of your book and generate your first DOI. We've tried to make this as painless as possible, but there are a few more steps to take initially. **For be able to initiate a release, you must have admin-level access to the Cookbook repository.** As always, reach out to a Pythia team member for help with any of these steps! @@ -256,24 +254,30 @@ As always, reach out to a Pythia team member for help with any of these steps! 1. Make a new release of your Cookbook repository! This is on the right nav side of the page from your code-view in the repository. 1. The DOI will now be generated automatically. The DOI badge on your homepage should link to the new archive that was just created on Zenodo. -### Initiate the Cookbook review process + +## I. Publish Your Cookbook on the Pythia Cookbook Gallery + +Once you're happy with your content and your Cookbook is building and deploying properly, it's time to think about submitting it for inclusion in the [Cookbook Gallery](https://cookbooks.projectpythia.org/)! + +```{note} +Cookbooks don't need to be "finished" in order to accepted in the Gallery! Cookbooks are typically accepted so long as they run cleanly, are free of obvious errors, and have some relevant new content. + +Cookbooks are meant to be living documents. We encourage authors to open GitHub issues to track progress on adding and updating content. +``` + +At this stage, there are a few more steps to get things ready to go. + + +### 1. Initiate the Cookbook review process If you haven't already, now is a great time to [contact the Project Pythia team](https://discourse.pangeo.io/c/education/project-pythia/60) to let them know about your new Cookbook. You will be assigned a Cookbook advocate from the Pythia maintenance team. They will open an issue on your Cookbook repository with the [Cookbook Checklist](cookbook-tasklist.md) for you to document your completion of the above process, plus a few more GitHub-specific steps. Once you complete this process, your Cookbook will be ready for review and publication! -### Submit your Cookbook to the Gallery - -Click the button below to request addition of your Cookbook to the [Project Pythia Cookbook Gallery](https://cookbooks.projectpythia.org). - - - - Submit a new Cookbook - - +### 2. Submit your Cookbook to the Gallery -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 take a look at your content, and work with you on any necessary updates and fixes. +1. Following fork-branch workflows, append the [`cookbook-gallery/cookbook_gallery.txt`](https://github.com/ProjectPythia/cookbook-gallery/blob/main/cookbook_gallery.txt) file to include the root name of your repository (e.g., just "cesm-cookbook", not the whole URL). +2. Open a Pull Request and tag a Project Pythia team member for review. +3. The Pythia team will take a look at your content, and work with you on any necessary updates and fixes. __*THANK YOU FOR YOUR AMAZING CONTRIBUTION TO THIS COMMUNITY RESOURCE!*__ diff --git a/portal/quick-cookbook-guide.md b/portal/quick-cookbook-guide.md new file mode 100644 index 00000000..3401f43c --- /dev/null +++ b/portal/quick-cookbook-guide.md @@ -0,0 +1,64 @@ +# Quick Guide to Contributing a New Cookbook + +This document is designed be lightweight. For more detailed, step-by-step instuctions, see the **Full Guide for Cookbook Guide** +

+ + Contributing a New Cookbook → + +

+ + +--- +## 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 your **thumbnail** to visually represent your work +- Update `README.md` to reflect: + - Title + - Description + - Motivation + - Authors + - Content structure + +- Update `myst.yml` with: + - Title + - GitHub link + - Table of contents (`toc`) + - Jupyter → Binder → Repo links + +- Update `CITATION.cff` with: + - Authors’ names, ORCID, website, and affiliation + - Title + - Abstract + +- Update `_gallery_info.yml` with: + - "packages" and "domains" tags + - the correct filepath for your thumbnail + +--- + +## 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**