From b0b4396aec686ed5dff988e329d4747f2d64bf73 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Tue, 22 Jun 2021 20:49:20 +0300 Subject: [PATCH 1/2] Reorganize site to group related content together. --- site/applications.md | 16 +++++ site/contributing.md | 127 ++++++++++++++++++++++++++++++++++++++ site/features.md | 14 +++++ site/index.md | 143 ++----------------------------------------- 4 files changed, 161 insertions(+), 139 deletions(-) create mode 100644 site/applications.md create mode 100644 site/contributing.md create mode 100644 site/features.md diff --git a/site/applications.md b/site/applications.md new file mode 100644 index 00000000..9fccf484 --- /dev/null +++ b/site/applications.md @@ -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 +``` diff --git a/site/contributing.md b/site/contributing.md new file mode 100644 index 00000000..8985c56c --- /dev/null +++ b/site/contributing.md @@ -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 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. + + + +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 diff --git a/site/features.md b/site/features.md new file mode 100644 index 00000000..c195b07e --- /dev/null +++ b/site/features.md @@ -0,0 +1,14 @@ +# NumPy Features + +A collection of tutorials, how-tos, and explanations pertaining to built-in +NumPy functionality. + +```{toctree} +--- +maxdepth: 1 +--- + +content/tutorial-svd +content/save-load-arrays +content/tutorial-ma +``` diff --git a/site/index.md b/site/index.md index aaf77a0d..b35127a1 100644 --- a/site/index.md +++ b/site/index.md @@ -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 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. - -
    -
    - - Fork this repository (if you haven't before). - - -
    - -
    - - In your own fork, create a new branch for your content. - - -
    - -
    - - Add your notebook to the content/ directory. - - -
    - -Update the environment.yml file with the dependencies for your tutorial -(only if you add new dependencies). - -
    - - Update this README.md to include your new entry. - - -
    - -
    - - Create a pull request. Make sure the "Allow edits and access to secrets by maintainers" option is selected so we can properly review your submission. - - -
    - -🎉 Wait for review! -
- -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: From 970b0c069dd69ca8c270f82d91db5a497e3e1ea8 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Wed, 23 Jun 2021 11:52:03 +0300 Subject: [PATCH 2/2] Reword to avoid big-picture questions. --- site/features.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/site/features.md b/site/features.md index c195b07e..fb966a8a 100644 --- a/site/features.md +++ b/site/features.md @@ -1,7 +1,6 @@ # NumPy Features -A collection of tutorials, how-tos, and explanations pertaining to built-in -NumPy functionality. +A collection of notebooks pertaining to built-in NumPy functionality. ```{toctree} ---