Cookbook pre-review checklist template

[dcamron]

This PR publishes a publicly viewable pre-review template for Cookbook authors. Our Cookbook "advocates" (shepherds in some discussions) should use this template as the checklist for a new issue in the Cookbooks they are supporting towards publication. We don't have a review process in place, but this should help get our hackathon Cookbooks published and serve as the baseline of the review process as we continue to develop it. The images won't resolve until this PR goes in, so below I've previewed what the checklist will look like with the current template in the PR:

PREVIEW BELOW

I am your Cookbook advocate, and my GitHub handle is . Please tag me in this issue with any problems getting your Cookbook published!
Once we've marked this entire checklist, click here to open an issue on ProjectPythia/cookbook-gallery to publish your Cookbook!

---

• Confirm you’ve followed the entire Project Pythia Cookbook Guide.
  Take note especially of the Develop your cookbook, Authorship and the CITATION.cff file, and Gallery tags sections. Save the Generate a DOI step as the last step of this checklist.
• Confirm that the individual notebooks within your Cookbook adhere to the notebook template.
  If the template does not fit your Cookbook’s needs, that’s fine too! Simply let us know here in this issue.
• Finalize your Cookbook repository name.
  We generally encourage the <content>-cookbook name structure.
• Finalize your environment.yml.
  Specify the minimum number of packages needed to reproduce your content. Document any necessary conflicts and pinned package versions in an issue. In your Cookbook README or a content preamble, describe any unique dependencies handled outside the conda environment.
• Sufficiently document your code with markdown narrative text, supplementary media and references, and citations.
  Declare any necessary prerequisite learning for each notebook at the top; these can be materials within your Cookbook, within other Cookbooks, or outside Project Pythia altogether.
• Review whether your Cookbook needs an Appendix of terms, definitions, or concepts.
  Additionally, should your Cookbook reference other Cookbooks and learning materials to support your content? Could supporting content be added as updates to Foundations or other Cookbooks benefit your Cookbook?
• Execute the trigger-replace-links action provided to your Cookbook.
  This will update any links to the Cookbook template to refer to your finalized repository name. See Links that need updating for a new cookbook created from this template cookbook-template#183 for manual references to these links if needed.
  • Click the Actions tab for your repository.
    
  • Highlight the trigger-replace-links action in the workflows sidebar.
    
  • On the right-hand side of the page, Run workflow > on Branch: Main.
    
• Fill in all template sections of your README.
  This will serve as your Cookbook homepage
  • Title
  • Cookbook description (brief, under title)
  • Cookbook Motivation - use this as an opportunity to tell us how your Cookbook fits in the broader learning ecosystem. Who should use this book? Why is it needed? Where does its content begin and end relative to existing resources?
  • Structure - this section is an optional roadmap for Cookbooks with more complicated structure. If you only have one main body of content that progresses linearly, you can leave this out.
• Confirm that your Cookbook is successfully building and publishing via GitHub Actions.
  This can be seen in individual Pull Requests as green checkmarks ✅ for important automation, especially the trigger-book-build action. You can also view a historical list of any of these Actions in the Actions tab at the top of your Cookbook repository. Check out nightly-build and trigger-book-build of PRs, then the build/build jobs to identify code errors. Please comment in this thread if you have issues identifying the source of any build and publishing failures your Cookbook has. Common failures include
  • Incorrectly specified environment.yml
  • trigger-link-check will fail if links in your content can not be resolved. We can help ignore links that are broken even if they work on manual clicks.
  • Code errors in your notebooks themselves
• Identify a Maintainer team via GitHub handle(s) in this thread.
  This can be one or more people with availability to check in on this Cookbook, issue fixes to broken content, or with a vision for the future development of the Cookbook. This is typically (but not necessarily) one of the primary authors of the Cookbook.
• Link your Cookbook repo to Zenodo for DOI generation
  Follow steps 1-4 under Generate a DOI in the Cookbook Guide. Return here for instructions on step 5, and your final step:
• Release your Cookbook!
  • On the right-hand sidebar for your Cookbook repository, click “Create a new release”. If you don’t see this button, you may need to click on the “Releases” header first and “Create” or “Draft” a new release.
    
  • “Choose a tag”, enter a new tag name. This will be the git reference of the snapshot of code that represents this particular release of your Cookbook! We recommend using a name fitting the CalVer scheme, so something like v2024.06.13 for the date of the release, then choose “+ Create new tag: on publish” and make its Target main (unless you have the knowledge and desire to release from another branch!)
    
  • From here you can use GitHub’s nifty “Generate release notes” button to automatically draft a summary of your Cookbook release based on merged Pull Requests! Feel free to further modify the title and body text of your release notes to fit your Cookbook and best represent your authors.
  • Finally, Publish release!

[github-actions]

👋 Thanks for opening this PR! The Cookbook will be automatically built with GitHub Actions. To see the status of your deployment, click below.
🔍 Git commit SHA: ff0bb18
✅ Deployment Preview URL: https://projectpythia.github.io/_preview/451

[dcamron]

I've also added sphinx-copybutton from EBP to make copying the template easier for advocates

[clyne]

This looks great, @dcamron! Thanks for submitting this.

[brian-rose]

Overall this looks great! I made a few suggestions that I hope help clarify the expected order of events in most cases.

[r-ford]

There was some issue with the build.