Skip to content
Merged

Typo #30

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
4 changes: 2 additions & 2 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ repos:
- id: double-quote-string-fixer

- repo: https://github.com/pre-commit/mirrors-prettier
rev: v2.4.0
rev: v2.4.1
hooks:
- id: prettier
exclude: "_templates/layout.html"
Expand All @@ -28,7 +28,7 @@ repos:
args: [--max-line-length=105]

- repo: https://github.com/psf/black
rev: 21.8b0
rev: 21.9b0
hooks:
- id: black
language_version: python3
Expand Down
76 changes: 48 additions & 28 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,20 @@
# Contribution guidance

This page documents the procedures for:

1. [Requesting new notebooks](#requesting-new-notebooks) to be added to the [IOOS CodeLab](https://ioos.github.io/ioos_code_lab);
1. [Building](#building-new-notebooks) new notebooks;
1. [Reviewing](#reviewing) submitted notebooks;
1. [Merging](#merging) approved notebooks for inclusion into the Code Gallery;
1. [Announcing](#announcing) the new notebooks to the community; and
1. [Announcing](#announcing) the new notebooks to the community; and
1. [Logging any bugs](#logging-bugs) that are found in the Code Gallery.
1. Managing the IOOS Data Demo Center [Project Board](#managing-ioos-data-demo-center-project-board).
1. [Local management](#local-management-of-notebooks_demo) of the notebooks_demo repository.

## Requesting new notebooks
* New notebooks should be requested by adding a [ticket](https://github.com/ioos/ioos_code_lab/issues/new) to this GitHub repository. The ticket should contain the following information:

- New notebooks should be requested by adding a [ticket](https://github.com/ioos/ioos_code_lab/issues/new) to this GitHub repository. The ticket should contain the following information:

```
- [ ] What is language(s) for used in the example?
- [ ] Is it focused on a particular module/software or an IOOS data service?
Expand All @@ -20,35 +24,40 @@ Please provide a detailed description of the suggested example below:
```

### For the admin

When the ticket gets created, make the following additions to the ticket:
* Add the label [Notebook idea](https://github.com/ioos/ioos_code_lab/labels/Notebook%20idea).
* Add the ticket to the [IOOS CodeLab](https://github.com/orgs/ioos/projects/1#card-49928448) project.
* Put the card in the column [backlog](https://github.com/orgs/ioos/projects/1#column-5010196).

- Add the label [Notebook idea](https://github.com/ioos/ioos_code_lab/labels/Notebook%20idea).
- Add the ticket to the [IOOS CodeLab](https://github.com/orgs/ioos/projects/1#card-49928448) project.
- Put the card in the column [backlog](https://github.com/orgs/ioos/projects/1#column-5010196).

## Building new notebooks

If you would like to work on a notebook that has been proposed, follow these steps:

1. [Create a fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of the [notebooks_demos](https://github.com/ioos/ioos_code_lab) repository.
1. On your fork, [create a branch](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository) where you will start working on the new notebook.
1. On your fork, [create a branch](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository) where you will start working on the new notebook.
1. Give the branch a name that conveys what the new notebook is. For example, a notebook on converting data into Darwin Core could have a branch name of `data2dwc`. This makes it easier to know which branch is dedicated to which new notebook.
1. On the new branch in your fork, start creating the new notebook.
1. On the new branch in your fork, start creating the new notebook.
1. Notebooks are kept in the [jupyterbook/content/code_gallery](https://github.com/ioos/ioos_code_lab/tree/master/jupyterbook/content/code_gallery) directory of this repository.
1. There are three directories where notebooks can be placed:
1. `data_access_notebooks` -
1. `data_access_notebooks` -
2. `data_analysis_and_visualization_notebooks` -
3. `data_management_notebooks` -
3. `data_management_notebooks` -
2. Typically, it's best to copy an existing (working) notebook to a new file. If you are creating a python notebook, copy one of the python notebooks. If you are creating an R notebook, copy one of the R notebooks, etc
3. Name the notebook following the convention `[date]-[short name].ipynb`. Where, `[date]` is the date (YYYY-MM-DD) you started the new notebook and `[short name]` is an abbreviation for what the notebook will cover. Look at the existing notebook filenames to get a sense of the short names used.
3. Name the notebook following the convention `[date]-[short name].ipynb`. Where, `[date]` is the date (YYYY-MM-DD) you started the new notebook and `[short name]` is an abbreviation for what the notebook will cover. Look at the existing notebook filenames to get a sense of the short names used.
1. Edit the notebook following the [Jupyter Notebook documentation](https://jupyter-notebook.readthedocs.io/en/stable/notebook.html).
1. Once you feel comfortable with your notebook, [commit](https://github.com/git-guides/git-commit) your work to the branch on your fork on your local machine.
1. Once you feel comfortable with your notebook, [commit](https://github.com/git-guides/git-commit) your work to the branch on your fork on your local machine.
1. [Push](https://github.com/git-guides/git-push) your commit up to the branch on your fork in GitHub.
1. [Create a Pull Request (PR)](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork).
1. Link the PR to the ticket requesting the new notebook.
1. On the right hand side of the PR there is an option for `Linked issues`. Type the number for the issue there (or scroll through the tickets until you find the one of interest).
1. Link the PR to the ticket requesting the new notebook.
1. On the right hand side of the PR there is an option for `Linked issues`. Type the number for the issue there (or scroll through the tickets until you find the one of interest).
1. **Admin** Move the Project card from `Backlog` to `Working`.
1. When you are ready for it to be merged, in the PR click `Ready for review`.
1. **Admin** Move the Project card from `Working` to `Needs Review`.

## Reviewing

See [pull request reviews](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews) for more information on reviewing PRs.

**Each new notebook needs at least one reviewer.**
Expand All @@ -62,17 +71,21 @@ See [pull request reviews](https://docs.github.com/en/github/collaborating-with-
1. Check for spelling errors.

## Merging

For Admins:

1. If the notebook looks good, the reviewer will [merge the PR](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/merging-a-pull-request).
1. This kicks off a series of [GitHub Actions](https://github.com/features/actions).
1. You can see the workflows at https://github.com/ioos/notebooks_demos/actions
1. You can see the workflows at https://github.com/ioos/notebooks_demos/actions
1. Once the workflows are complete, check the [IOOS CodeLab](https://ioos.github.io/ioos_code_lab/) for the new notebook.
1. Review the notebook for any display issues when presented on the web. Check for the extra cell at the bottom of the notebook.
1. Review the notebook for any display issues when presented on the web. Check for the extra cell at the bottom of the notebook.
1. If there are issues, submit a new PR to resolve the issues.

## Announcing

When new notebooks, or significant changes to the site, are merged and pushed out, follow this procedure:
1. **Admin** Move the appropriate Project card to [Announcement](https://github.com/orgs/ioos/projects/1#column-13186308).

1. **Admin** Move the appropriate Project card to [Announcement](https://github.com/orgs/ioos/projects/1#column-13186308).
1. Draft announcement text.
1. Include a brief summary of the new release.
1. Include any relevant links to the demo center.
Expand All @@ -85,48 +98,55 @@ When new notebooks, or significant changes to the site, are merged and pushed ou
1. Appropriate slack channels

## Logging bugs or changes

1. Bugs should be reported through tickets in this repository. Be sure to include the notebook where the problem is found. Include a clear description of the issue or change that is needed.

## Managing IOOS Data Demo Center Project Board

The [project board](https://github.com/orgs/ioos/projects/1) captures the current progress on notebooks and adjustments to the IOOS Data Demo Center.

| **Column name** | **Purpose** |
------------------|--------------
Icebox | Back burner tickets to keep in the fray.
Backlog | Tickets to be worked on next.
Working | Tickets actively being contributed to.
Needs Review | Tickets where a PR has been requested to merge.
Announcement | Tickets that have been merged and an announcement needs to be made.
Done | All completed tickets.
| **Column name** | **Purpose** |
| --------------- | ------------------------------------------------------------------- |
| Icebox | Back burner tickets to keep in the fray. |
| Backlog | Tickets to be worked on next. |
| Working | Tickets actively being contributed to. |
| Needs Review | Tickets where a PR has been requested to merge. |
| Announcement | Tickets that have been merged and an announcement needs to be made. |
| Done | All completed tickets. |

## Local management of notebooks_demo

This section walks through one way to manage the notebooks_demo git repository on your local machine.

Clone your fork of the notebooks_demo repository to a known location on your machine:
Clone your fork of the notebooks_demo repository to a known location on your machine:

```$ git clone https://github.com/MathewBiddle/ioos_code_lab.git```
`$ git clone https://github.com/MathewBiddle/ioos_code_lab.git`

Set the upstream branch to the ioos/notebooks_demos repository:

```$ git remote add upstream https://github.com/ioos/ioos_code_lab.git```
`$ git remote add upstream https://github.com/ioos/ioos_code_lab.git`

Keep your local main up-to-date with the upstream main ([walkthough](https://stefanbauer.me/articles/how-to-keep-your-git-fork-up-to-date)):

```
$ git fetch upstream
$ git pull upstream/main main
```

OR

```
$ git merge upstream/main main
```

Rebase (if needed):

```
$ git rebase upstream/main
```

Push your local repo up to your fork in GitHub.

```
$ git push
```
```
41 changes: 30 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# IOOS CodeLab

The [IOOS CodeLab](https://ioos.github.io/ioos_code_lab) is a collection of tutorials and examples of how to access and
utilize the many IOOS technologies and data sources available. This site is geared towards scientists and environmental
managers interested in “diving deep” into the numbers and creating original plots and data analysis. Most notebook
The [IOOS CodeLab](https://ioos.github.io/ioos_code_lab) is a collection of tutorials and examples of how to access and
utilize the many IOOS technologies and data sources available. This site is geared towards scientists and environmental
managers interested in “diving deep” into the numbers and creating original plots and data analysis. Most notebook
examples are written in Python, however, we also have a growing number of notebooks written in Matlab, and R.

See the rendered version at https://ioos.github.io/ioos_code_lab
Expand All @@ -17,54 +17,73 @@ To suggest a notebook or ask questions please open an issue at: https://github.c

[![DOI](https://zenodo.org/badge/399546690.svg)](https://zenodo.org/badge/latestdoi/399546690)

----
---

## Build the JupyterBook locally

### Resources:
* Jupyter-book command line interface: https://jupyterbook.org/basics/build.html

- Jupyter-book command line interface: https://jupyterbook.org/basics/build.html

### Requirements:

* Git: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
* Jupyter{Book}: https://jupyterbook.org/intro.html
* Web Browser
- Git: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
- Jupyter{Book}: https://jupyterbook.org/intro.html
- Web Browser

### Installation

Install jupyter-book:

```
conda install jupyter-book
```

Clone the [ioos_code_lab](https://github.com/ioos/ioos_code_lab) repository.

```
git clone https://github.com/ioos/ioos_code_lab.git
```
Once you have cloned the repository, you have all the required notebooks cloned onto your system
(in the `/jupyterbook/content` directory).

Once you have cloned the repository, you have all the required notebooks cloned onto your system
(in the `/jupyterbook/content` directory).

### Build the JupyterBook

Run the following command to build the JupyterBook.

```
jupyter-book build jupyterbook/
```

The command should be run relative to the `jupyterbook/` directory.

If you are in the `jupyterbook/` directory, you can build the book using

```
juyter-book build .
```

### View the built JupyterBook

Your book's HTML pages are here:

```
jupyterbook\_build\html\
```

You can look at your book by opening this file in a browser:

```
jupyterbook\_build\html\index.html
```

Or, use the full link displayed in the terminal to view the website.

### Clean up the book's generated files

To entirely remove the folders in the `_build/` directory:

```
jupyter-book clean jupyterbook/ --all
```
```

Large diffs are not rendered by default.

1 change: 0 additions & 1 deletion pytest.ini
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ addopts =
# Stale/won't fix/missing libray
--ignore="jupyterbook/content/code_gallery/data_access_notebooks/2016-12-22-boston_light_swim.ipynb"
--ignore="jupyterbook/content/code_gallery/data_access_notebooks/2017-03-21-ERDDAP_IOOS_Sensor_Map.ipynb"
--ignore="jupyterbook/content/code_gallery/data_access_notebooks/2017-06-12-NCEI_RA_archive_history.ipynb"
--ignore="jupyterbook/content/code_gallery/data_access_notebooks/2017-07-25-HFRadar_currents.ipynb"
--ignore="jupyterbook/content/code_gallery/data_access_notebooks/2017-12-15-finding_HFRadar_currents.ipynb"
--ignore="jupyterbook/content/code_gallery/data_analysis_and_visualization_notebooks/2017-03-30-octave_notebook_example.ipynb"
Expand Down