Substantial rewrite of the Cookbook guide

[brian-rose]

This PR get the Cookbook guide up to date and adds substantial detail on working with the Pythia infrastructure.

Closes #433

[github-actions[bot]]

👋 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: 3f525810d71bf6bb7a70f417890bfe4422f4d9ea ✅ Deployment Preview URL: https://projectpythia.github.io/_preview/435

[brian-rose]

Here's a direct link to the preview of the new guide, since it's a bit hard to get to from the regular preview link: https://projectpythia.org/_preview/435/cookbook-guide.html

[brian-rose]

I think all the changes here make sense.

This document is pretty large now, and I think it could be confusing for someone seeing it for the first time. I guess this is really a theme issue, but I can barely differentiate the heading levels, and there is no sidebar on the right with the section outline.

I had the same thought, I wished the level 2 and level 3 headings were easier to distinguish. I can try adding lines to separate the major sections.

Is the lack of a right sidebar a known theme issue? I see a button "toggle secondary sidebar" but it is non-functional.

[brian-rose]

Unfortunately horizontal lines don't help much because they are nearly invisible.

[brian-rose]

Also, a gh-pages website was never published, either in my personal repo or in the ProjectPythia repo for the cookbook. Not sure how to fix that.

It's here: https://projectpythia.org/hello-pythia-cookbook/README.html

[brian-rose]

Following the instructions I was able to create a test cookbook. However, I did receive an error in one of the GitHub Actions as noted in my in-line comments.

From what I can see here, all the actions are working as expected in the upstream fork.

[brian-rose]

@clyne thanks for the detailed read-through! I think I have addressed all your comments, and I added a bit more detail on making Pull Requests.

In retrospect, I think it might be better to separate this guide into two pieces:

• contributing to Cookbooks
• making new Cookbooks

But that could be left as an open issue for the future if we're reasonably happy with what's here.

[clyne]

Also, a gh-pages website was never published, either in my personal repo or in the ProjectPythia repo for the cookbook. Not sure how to fix that.

It's here: https://projectpythia.org/hello-pythia-cookbook/README.html

Sorry, should have been more clear. The gh-pages site is not linked from underneath the "About" heading on the repo website. Shouldn't this happen automatically?

[brian-rose]

Also, a gh-pages website was never published, either in my personal repo or in the ProjectPythia repo for the cookbook. Not sure how to fix that.

It's here: https://projectpythia.org/hello-pythia-cookbook/README.html

Sorry, should have been more clear. The gh-pages site is not linked from underneath the "About" heading on the repo website. Shouldn't this happen automatically?

No, it does not happen automatically. Maybe you missed my suggestion for this in this section under "Here's a handy trick..."

[clyne]

Also, a gh-pages website was never published, either in my personal repo or in the ProjectPythia repo for the cookbook. Not sure how to fix that.

It's here: https://projectpythia.org/hello-pythia-cookbook/README.html

Sorry, should have been more clear. The gh-pages site is not linked from underneath the "About" heading on the repo website. Shouldn't this happen automatically?

No, it does not happen automatically. Maybe you missed my suggestion for this in this section under "Here's a handy trick..."

No, I didn't miss it, but it explains the rabbit hole that I went down. The "About" settings are different for my personal repo, and do not include the option to "Use your GitHub Pages website". I probably got confused about which repo I was looking at. Here's a screenshot for what I see on my personal repo:

[brian-rose]

Also, a gh-pages website was never published, either in my personal repo or in the ProjectPythia repo for the cookbook. Not sure how to fix that.

It's here: https://projectpythia.org/hello-pythia-cookbook/README.html

Sorry, should have been more clear. The gh-pages site is not linked from underneath the "About" heading on the repo website. Shouldn't this happen automatically?

No, it does not happen automatically. Maybe you missed my suggestion for this in this section under "Here's a handy trick..."

No, I didn't miss it, but it explains the rabbit hole that I went down. The "About" settings are different for my personal repo, and do not include the option to "Use your GitHub Pages website". I probably got confused about which repo I was looking at. Here's a screenshot for what I see on my personal repo:

Oh, that makes sense! I will add a clarifying note. It's easy to get confused about which version of the repo one is looking at.

[clyne]

Also, a gh-pages website was never published, either in my personal repo or in the ProjectPythia repo for the cookbook. Not sure how to fix that.

It's here: https://projectpythia.org/hello-pythia-cookbook/README.html

Sorry, should have been more clear. The gh-pages site is not linked from underneath the "About" heading on the repo website. Shouldn't this happen automatically?

No, it does not happen automatically. Maybe you missed my suggestion for this in this section under "Here's a handy trick..."

No, I didn't miss it, but it explains the rabbit hole that I went down. The "About" settings are different for my personal repo, and do not include the option to "Use your GitHub Pages website". I probably got confused about which repo I was looking at. Here's a screenshot for what I see on my personal repo:

Oh, that makes sense! I will add a clarifying note. It's easy to get confused about which version of the repo one is looking at.

Cool. I'll be going offline soon and have approved the PR. Nice work!

[brian-rose]

Thanks so much @clyne for the careful review! Much appreciated.