Skip to content

Reorganize site to group related content together. #88

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.

Sign up for GitHub

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 2 commits into from
Jun 23, 2021
Merged

Reorganize site to group related content together. #88

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b0b4396
Reorganize site to group related content together.
rossbar Jun 22, 2021
970b0c0
Reword to avoid big-picture questions.
rossbar Jun 23, 2021
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
16 changes: 16 additions & 0 deletions site/applications.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# NumPy Applications

A collection of highlighting the use of NumPy for applications in science,
engineering, and data analysis.

```{toctree}
---
maxdepth: 1
---

content/mooreslaw-tutorial
content/tutorial-deep-learning-on-mnist
content/tutorial-deep-reinforcement-learning-with-pong-from-pixels
content/tutorial-x-ray-image-processing
content/tutorial-static_equilibrium
```
127 changes: 127 additions & 0 deletions site/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
# Contributing

We very much welcome contributions! If you have an idea or proposal for a new
tutorial, please [open an issue](https://github.com/numpy/numpy-tutorials/issues)
with an outline.

Don’t worry if English is not your first language, or if you can only come up
with a rough draft. Open source is a community effort. Do your best – we’ll help
fix issues.

Images and real-life data make text more engaging and powerful, but be sure what
you use is appropriately licensed and available. Here again, even a rough idea
for artwork can be polished by others.

The NumPy tutorials are a curated collection of
[MyST-NB](https://myst-nb.readthedocs.io/) notebooks. These notebooks are used
to produce static websites and can be opened as notebooks in Jupyter using
[Jupytext](https://jupytext.readthedocs.io).

> __Note:__ You should use [CommonMark](https://commonmark.org) markdown
> cells. Jupyter only renders CommonMark.

## Why Jupyter Notebooks?

The choice of Jupyter Notebook in this repo instead of the usual format
([reStructuredText][rst])
used in the main NumPy documentation has two reasons:


* Jupyter notebooks are a common format for communicating scientific
information.
* Jupyter notebooks can be launched in [Binder](https://www.mybinder.org), so that users can interact
with tutorials
* rST may present a barrier for some people who might otherwise be very
interested in contributing tutorial material.

[rst]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html

### Note

You may notice our content is in markdown format (`.md` files). We review and
host notebooks in the [MyST-NB](https://myst-nb.readthedocs.io/) format. We
accept both Jupyter notebooks (`.ipynb`) and MyST-NB notebooks (`.md`).
If you want to sync your `.ipynb` to your `.md` file follow the [pairing
tutorial](content/pairing.md).

```{toctree}
:hidden:

content/pairing
```

## Adding your own tutorials

If you have your own tutorial in the form of a Jupyter notebook (an `.ipynb`
file) and you'd like to try add it out to the repository, follow the steps below.

### Create an issue

Go to <https://github.com/numpy/numpy-tutorials/issues> and create a new issue
with your proposal.
Give as much detail as you can about what kind of content you would like to
write (tutorial, how-to) and what you plan to cover.
We will try to respond as quickly as possible with comments, if applicable.

### Check out our suggested template

You can use this template to make your content consistent with our existing
tutorials:

```{toctree}
---
maxdepth: 1
---
content/tutorial-style-guide
```

### Upload your content

Remember to clear all outputs on your notebook before uploading it.

<ul>
<details>
<summary>
<b>Fork this repository</b> (if you haven't before).
</summary>
<img src="_static/01-fork.gif" width=80% height=80%>
</details>

<details>
<summary>
<b>In your own fork, create a new branch for your content.</b>
</summary>
<img src="_static/02-create_new_branch.gif" width=80% height=80%>
</details>

<details>
<summary>
<b>Add your notebook to the <code>content/</code> directory.</b>
</summary>
<img src="_static/03-upload.gif" width=80% height=80%>
</details>

<b>Update the <code>environment.yml</code> file with the dependencies for your tutorial</b>
(only if you add new dependencies).

<details>
<summary>
<b>Update this <code>README.md</code> to include your new entry.</b>
</summary>
<img src="_static/04-add_to_readme.gif" width=80% height=80%>
</details>

<details>
<summary>
<b>Create a <a href="https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests">pull request.</a> Make sure the "Allow edits and access to secrets by maintainers" option is selected so we can properly review your submission.</b>
</summary>
<img src="_static/05-create_PR.gif" width=80% height=80%>
</details>

🎉 <b>Wait for review!</b>
</ul>

For more information about GitHub and its workflow, you can see
[this document][collab].

[collab]: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests
13 changes: 13 additions & 0 deletions site/features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# NumPy Features

A collection of notebooks pertaining to built-in NumPy functionality.

```{toctree}
---
maxdepth: 1
---

content/tutorial-svd
content/save-load-arrays
content/tutorial-ma
```
143 changes: 4 additions & 139 deletions site/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,149 +23,14 @@ or use the download icon in the upper-right corner of each tutorial.

```{toctree}
---
maxdepth: 1
maxdepth: 2
---

content/tutorial-style-guide
content/tutorial-svd
content/mooreslaw-tutorial
content/save-load-arrays
content/tutorial-deep-learning-on-mnist
content/tutorial-deep-reinforcement-learning-with-pong-from-pixels
content/tutorial-x-ray-image-processing
content/tutorial-ma
content/tutorial-static_equilibrium
features
applications
contributing
```

## Contributing

We very much welcome contributions! If you have an idea or proposal for a new
tutorial, please [open an issue](https://github.com/numpy/numpy-tutorials/issues)
with an outline.

Don’t worry if English is not your first language, or if you can only come up
with a rough draft. Open source is a community effort. Do your best – we’ll help
fix issues.

Images and real-life data make text more engaging and powerful, but be sure what
you use is appropriately licensed and available. Here again, even a rough idea
for artwork can be polished by others.

The NumPy tutorials are a curated collection of
[MyST-NB](https://myst-nb.readthedocs.io/) notebooks. These notebooks are used
to produce static websites and can be opened as notebooks in Jupyter using
[Jupytext](https://jupytext.readthedocs.io).

> __Note:__ You should use [CommonMark](https://commonmark.org) markdown
> cells. Jupyter only renders CommonMark.

### Why Jupyter Notebooks?

The choice of Jupyter Notebook in this repo instead of the usual format
([reStructuredText][rst])
used in the main NumPy documentation has two reasons:


* Jupyter notebooks are a common format for communicating scientific
information.
* Jupyter notebooks can be launched in [Binder](https://www.mybinder.org), so that users can interact
with tutorials
* rST may present a barrier for some people who might otherwise be very
interested in contributing tutorial material.

[rst]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html

#### Note

You may notice our content is in markdown format (`.md` files). We review and
host notebooks in the [MyST-NB](https://myst-nb.readthedocs.io/) format. We
accept both Jupyter notebooks (`.ipynb`) and MyST-NB notebooks (`.md`).
If you want to sync your `.ipynb` to your `.md` file follow the [pairing
tutorial](content/pairing.md).

```{toctree}
:hidden:

content/pairing
```

### Adding your own tutorials

If you have your own tutorial in the form of a Jupyter notebook (an `.ipynb`
file) and you'd like to try add it out to the repository, follow the steps below.

#### Create an issue

Go to <https://github.com/numpy/numpy-tutorials/issues> and create a new issue
with your proposal.
Give as much detail as you can about what kind of content you would like to
write (tutorial, how-to) and what you plan to cover.
We will try to respond as quickly as possible with comments, if applicable.

#### Check out our suggested template

You can use this template to make your content consistent with our existing
tutorials:

```{toctree}
---
maxdepth: 1
---
content/tutorial-style-guide
```

#### Upload your content

Remember to clear all outputs on your notebook before uploading it.

<ul>
<details>
<summary>
<b>Fork this repository</b> (if you haven't before).
</summary>
<img src="_static/01-fork.gif" width=80% height=80%>
</details>

<details>
<summary>
<b>In your own fork, create a new branch for your content.</b>
</summary>
<img src="_static/02-create_new_branch.gif" width=80% height=80%>
</details>

<details>
<summary>
<b>Add your notebook to the <code>content/</code> directory.</b>
</summary>
<img src="_static/03-upload.gif" width=80% height=80%>
</details>

<b>Update the <code>environment.yml</code> file with the dependencies for your tutorial</b>
(only if you add new dependencies).

<details>
<summary>
<b>Update this <code>README.md</code> to include your new entry.</b>
</summary>
<img src="_static/04-add_to_readme.gif" width=80% height=80%>
</details>

<details>
<summary>
<b>Create a <a href="https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests">pull request.</a> Make sure the "Allow edits and access to secrets by maintainers" option is selected so we can properly review your submission.</b>
</summary>
<img src="_static/05-create_PR.gif" width=80% height=80%>
</details>

🎉 <b>Wait for review!</b>
</ul>

For more information about GitHub and its workflow, you can see
[this document][collab].

[collab]: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests


## Useful links and resources

The following links may be useful:
Expand Down