Add Jupyter Book 2 / MyST conversion notes to a contributor's guide

[kafitzgerald]

During the Project Pythia Cookoff earlier this year and a follow on work session at SciPy some folks (myself included) put together a list of steps documenting how to convert an existing Project Pythia Cookbook to a Jupyter Book 2 / Myst Cookbook. These notes currently live in a shared Google Docs, but should move to a more public and Project Pythia owned location.

@jukent suggested one (or some) of the contributing guides as a good place to start looking.

I suspect the either the Cookbook Contributor's Guide or a new location would be the place to add this.

Including the list of steps below as well in case there's some discussion needed re: where they should live.

Steps to convert an existing Project Pythia Cookbook from Jupyter Book 1 to Jupyter Book 2 / MyST:

1. Request to be added to the https://github.com/projectpythia-mystmd/ GitHub organization
2. Fork your existing (non-converted) Project Pythia Cookbook into the projectpythia-mystmd GitHub organization
3. Clone your repository
4. Add mystmd to your environment.yml file
5. Create a new environment from the updated environment file ​​conda env create -f environment.yml and activate your environment
6. Initialize MyST-MD myst init --write-toc and answer n for if you want to run myst start now (unless you’d like to check out a local version of it)
7. Generate a GitHub Actions workflow via myst init --gh-pages, answering the prompts accordingly for deploying it from main and calling it deploy.yml
8. Edit your configuration file to use the Pythia configuration by adding the highlighted lines to your myst.yml
9. Edit your configuration file to use Jupyter by adding these highlighted lines to your myst.yml and updating the repository info to reflect the current project
10. Edit your configuration file to add the appropriate metadata e.g. title, authors, copyright, keywords (new), etc. and/or port it over from the old _config.yml file. You can find more information about all of the available options here in the documentation
11. Reference conversion currently will be missing the combined references section at the end since this is not something MyST currently supports. Instead it will automatically generate a references section for each notebook. It also doesn’t include a references header on the right menu bar, but will automatically pick up your existing BibTeX file without specification
    • Remove existing reference sections at the end of notebooks since these will be duplicated
    • Remove broken combined reference section (i.e. references.md)
12. Start things up to check it out locally [optional]: myst start --execute
13. Stage and commit your updated configurations files and push to GitHub. Be sure to include .github/workflows/deploy.yml and myst.yml.
14. Activate GitHub Pages in Settings > Pages and change the source to GitHub Actions
15. Turn on GitHub Actions [may not be needed]
    • Go to the Settings tab of your forked repo
    • Go to Actions > General in the menu on the left
    • Enable “Allow all actions and reusable workflows” under Actions Permissions
16. Change the link to the deployment in your forked repository’s About section to the new URL [optional, but nice]
17. View your newly deployed cookbook! 🎉
18. Add your new MySTified cookbook to the demo gallery by editing this file

[jukent]

Between steps 2 and 3, fork the repository into your own workspace before cloning

Additional steps:

• Update the URL in the About section of the repository site
• Update the README.md nightly build and binder badges

[kafitzgerald]

Between steps 2 and 3, fork the repository into your own workspace before cloning

Yeah, this was very much catered to the earlier hackathons / sprints where we all had permissions in the new organization.

There might be some other changes needed as well.

[brian-rose]

Is this something that we want to preserve and make public, or is this more internal documentation that has largely served its purpose since most repos have been migrated?

[kafitzgerald]

Is this something that we want to preserve and make public, or is this more internal documentation that has largely served its purpose since most repos have been migrated?

I think primarily the latter at this point (unless there are WIP cookbooks that we're unaware of).

I'll go ahead and close this out.