Skip to content

📖 Fix note directive #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 13, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions portal/contributing.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Project Pythia Contributor's Guide

```{Note}
```{note}
This the top-level guide for Project Pythia and a great starting point for getting involved!

We also have specific guides for
Expand Down Expand Up @@ -143,7 +143,7 @@ command line tool for collaborative software version control, while
GitHub is an online, web-accessible service that greatly simplifies
using the powerful, yet often complex, Git.

```{Note}
```{note}
GitHub operates entirely within a web browser. You do not
need to install anything, but you will need to set up a free GitHub
account. Git is a command line tool that is most likely already
Expand Down Expand Up @@ -225,7 +225,7 @@ you wish to use it. Consult the repo-specific contributor’s guide
for information on “Building the site”, and
follow the steps described therein.

```{Note}
```{note}
Repository-specific contributor's
information can always be accessed by navigating your web browser
to the appropriate Project Pythia GitHub repository,
Expand Down Expand Up @@ -326,7 +326,7 @@ on this later.

For further information see the [GitHub docs on forking a repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo).

```{Note}
```{note}
At this point you should have a local copy of the repository
in your current working directory. You can safely make changes to
any of the contents. Once you are ready to contribute your changes
Expand Down Expand Up @@ -390,7 +390,7 @@ $ git commit PATH_TO_NEW_FILE

Which will prompt you for a log message. Please provide something informative. If you make lots of changes, it is best to make multiple commits, broken up into related chunks. E.g. “fixed x”, “added documentation”, “added testing”.

```{Note}
```{note}
When executing `git commit` after `git add PATH_TO_NEW_FILE`,
specifying the path to the new file isn't stricly necessary. However,
in other instances the file path argument is required. We include it
Expand All @@ -411,7 +411,7 @@ $ git status

after your `commit` to verify everything looks as expected.

```{Note}
```{note}
`pre-commit` _hooks_ can sometimes be difficult to satisfy. You
can always tell **git** not to run the _hook_ by
running `git commit --no-verify`.
Expand Down
18 changes: 9 additions & 9 deletions portal/cookbook-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ The following is a step-by-step guide to creating a new Cookbook and getting it

Before you begin, ask yourself if the content you are developing for a cookbook would be better suited as an addition to an existing cookbook. The best place to discuss cookbook ideas is the [Project Pythia category of the Pangeo Discourse](https://discourse.pangeo.io/c/education/project-pythia/60).

```{Note}
```{note}
These instructions assume that your goal is to contribute a new Cookbook to the community-maintained collection housed on the [Pythia Cookbook Gallery](https://cookbooks.projectpythia.org).

Using the Pythia Cookbook template to create reproducible documents housed elsewhere is definitely possible! But we don't focus on that use case in this guide.
Expand Down Expand Up @@ -39,7 +39,7 @@ Before developing your cookbook, you should consider how it will access the data

Your cookbook is now ready to have content added!

```{Note}
```{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).
```

Expand All @@ -54,7 +54,7 @@ However, we recommend transfering to the Pythia organization early, for a few re
- Easier to get help from the Pythia infrastructure team
- Encourages collaboration

```{Note}
```{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...)
Expand Down Expand Up @@ -99,7 +99,7 @@ Your repository includes automation for building and publishing your Cookbook, p

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 `<your-cookbook-name>-dev`). Commit these changes.

```{Note}
```{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.
```

Expand Down Expand Up @@ -167,7 +167,7 @@ Here's a handy trick for finding your published book:

The link to your published book will then be displayed on the home page of the repo.

```{Note}
```{note}
If you have transfered your repository to the ProjectPythia organization and also made a personal fork, the publishing pipeline automation will _only run on the upstream fork on the ProjectPythia organization_ so there's only one copy of the "published" book.

It's possible to enable the workflows on your personal fork, but usually unneccesary if you preview your work via Pull Requests (see next section)!
Expand All @@ -187,7 +187,7 @@ Not satisfied? Keep making changes! Every new push to the feature branch on your

### Building on the Pythia Binder

```{Note}
```{note}
By default, notebooks are executed on the free GitHub Actions service. This works fine for most lightweight Cookbooks. If your book is building and publishing succesfully, you can safely ignore this section!
```

Expand All @@ -200,15 +200,15 @@ Here's how:
- That will trigger a build and preview as usual, but the notebook execution will happen on the Binder.
- If all is well, merge the changes, and all further builds will work this way.

```{Note}
```{note}
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 submiting it for inclusion in the [Cookbook Gallery](https://cookbooks.projectpythia.org/)!

```{Note}
```{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.
Expand All @@ -231,7 +231,7 @@ Edit `CITATION.cff` as follows:
- 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}
```{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!
```

Expand Down
Loading