diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..13ed7d44 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,117 @@ +# 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. + +## Building the website + +```{note} +The NumPy tutorials are powered by [`jupyter-book`][jb-docs] and the +[`MyST` document engine][mystmd]. +See the linked documentation for further details. +``` + +[jb-docs]: https://jupyterbook.org/stable/ +[mystmd]: https://mystmd.org/ + +### Quickstart + +Set up a development environment with the dependencies listed in +`requirements.txt` and `site/requirements.txt`. +For example, using the built-in [`venv`][venv] module: + +```bash +python -m venv np-tutorials +source np-tutorials/bin/activate +python -m pip install -r requirements.txt -r site/requirements.txt +``` + +[venv]: https://docs.python.org/3/library/venv.html + +The site can then be built with: + +```bash +jupyter-book start --execute +``` + +This will execute all the notebooks and start a web server to view the rendered +content locally. +View the rendered site by opening the ``localhost:30xy`` in your preferred browser (the exact port number will be printed in your terminal). + +## 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. + +### 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/README.md b/README.md index 8dbce9ca..5109e2c9 100644 --- a/README.md +++ b/README.md @@ -25,136 +25,6 @@ or navigate to any of the documents listed below and download it individually. 8. [Tutorial: Plotting Fractals](content/tutorial-plotting-fractals.ipynb) 9. [Tutorial: Analysing the impact of the lockdown on air quality in Delhi, India](content/tutorial-air-quality-analysis.md) - -## 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, through Sphinx](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html)) -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. - -#### 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 author `MyST` notebooks in jupyterlab, check out the -[jupyterlab_myst](https://mystmd.org/guide/quickstart-jupyter-lab-myst) extension! - - -### Adding your own tutorials - -If you have your own tutorial in the form of a Jupyter notebook (a `.ipynb` -file) and you'd like to add it to the repository, follow the steps below. - - -#### Create an issue - -Go to [https://github.com/numpy/numpy-tutorials/issues](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 our [Tutorial Style Guide](content/tutorial-style-guide.md) to make -your content consistent with our existing tutorials. - -#### Upload your content - - - -For more information about GitHub and its workflow, you can see -[this document](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests). - - -### Building the Sphinx site locally - -Building the tutorials website, which is published at -https://github.com/numpy/numpy-tutorials, locally isn't necessary before making -a contribution, but may be helpful: - -```bash -conda env create -f environment.yml -conda activate numpy-tutorials -cd site -make html -``` - ## Translations While we don't have the capacity to translate and maintain translated versions diff --git a/content/mooreslaw-tutorial.md b/content/mooreslaw-tutorial.md index 9fc216d2..638853c4 100644 --- a/content/mooreslaw-tutorial.md +++ b/content/mooreslaw-tutorial.md @@ -60,8 +60,8 @@ You'll use these NumPy and Matplotlib functions: * [`np.log`](https://numpy.org/doc/stable/reference/generated/numpy.log.html): this function takes the natural log of all elements in a NumPy array * [`np.exp`](https://numpy.org/doc/stable/reference/generated/numpy.exp.html): this function takes the exponential of all elements in a NumPy array * [`lambda`](https://docs.python.org/3/library/ast.html?highlight=lambda#ast.Lambda): this is a minimal function definition for creating a function model -* [`plt.semilogy`](https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.semilogy.html): this function will plot x-y data onto a figure with a linear x-axis and $\log_{10}$ y-axis -[`plt.plot`](https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.plot.html): this function will plot x-y data on linear axes +* [`plt.semilogy`](https://matplotlib.org/api/_as_gen/matplotlib.pyplot.semilogy.html): this function will plot x-y data onto a figure with a linear x-axis and $\log_{10}$ y-axis +[`plt.plot`](https://matplotlib.org/api/_as_gen/matplotlib.pyplot.plot.html): this function will plot x-y data on linear axes * slicing arrays: view parts of the data loaded into the workspace, slice the arrays e.g. `x[:10]` for the first 10 values in the array, `x` * boolean array indexing: to view parts of the data that match a given condition use boolean operations to index an array * [`np.block`](https://numpy.org/doc/stable/reference/generated/numpy.block.html): to combine arrays into 2D arrays @@ -259,7 +259,7 @@ year. Now compare your model to the actual manufacturing reports. Plot the linear regression results and all of the transistor counts. Here, use -[`plt.semilogy`](https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.semilogy.html) +[`plt.semilogy`](https://matplotlib.org/api/_as_gen/matplotlib.pyplot.semilogy.html) to plot the number of transistors on a log-scale and the year on a linear scale. You have defined a three arrays to get to a final model @@ -280,11 +280,11 @@ $\text{transistor_count}_{\text{predicted}} = e^Be^{A\cdot \text{year}}$. +++ In the next plot, use the -[`fivethirtyeight`](https://matplotlib.org/3.1.1/gallery/style_sheets/fivethirtyeight.html) +[`fivethirtyeight`](https://matplotlib.org/gallery/style_sheets/fivethirtyeight.html) style sheet. The style sheet replicates elements. Change the matplotlib style with -[`plt.style.use`](https://matplotlib.org/3.3.2/api/style_api.html#matplotlib.style.use). +[`plt.style.use`](https://matplotlib.org/api/style_api.html#matplotlib.style.use). ```{code-cell} transistor_count_predicted = np.exp(B) * np.exp(A * year) @@ -329,9 +329,9 @@ $\text{transistor_count} = e^{B}e^{A\cdot \text{year}}$. A great way to compare these measurements is to compare your prediction and Moore's prediction to the average transistor count and look at the range of reported values for that year. Use the -[`plt.plot`](https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.plot.html) +[`plt.plot`](https://matplotlib.org/api/_as_gen/matplotlib.pyplot.plot.html) option, -[`alpha=0.2`](https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.artist.Artist.set_alpha.html), +[`alpha=0.2`](https://matplotlib.org/api/_as_gen/matplotlib.artist.Artist.set_alpha.html), to increase the transparency of the data. The more opaque the points appear, the more reported values lie on that measurement. The green $+$ is the average reported transistor count for 2017. Plot your predictions diff --git a/content/tutorial-plotting-fractals.md b/content/tutorial-plotting-fractals.md index a1921cea..beb64e6d 100644 --- a/content/tutorial-plotting-fractals.md +++ b/content/tutorial-plotting-fractals.md @@ -110,7 +110,7 @@ mesh = x + (1j * y) # Make mesh of complex plane Now we will apply our function to each value contained in the mesh. Since we used a universal function in our design, this means that we can pass in the entire mesh all at once. This is extremely convenient for two reasons: It reduces the amount of code needed to be written and greatly increases the efficiency (as universal functions make use of system level C programming in their computations). -Here we plot the absolute value (or modulus) of each element in the mesh after one “iteration” of the function using a [**3D scatterplot**](https://matplotlib.org/2.0.2/mpl_toolkits/mplot3d/tutorial.html#scatter-plots): +Here we plot the absolute value (or modulus) of each element in the mesh after one “iteration” of the function using a [**3D scatterplot**](https://matplotlib.org/stable/users/explain/toolkits/mplot3d.html#scatter-plots): ```{code-cell} ipython3 output = np.abs(f(mesh)) # Take the absolute value of the output (for plotting) diff --git a/content/tutorial-static_equilibrium.md b/content/tutorial-static_equilibrium.md index 2d1a4d3e..29164be9 100644 --- a/content/tutorial-static_equilibrium.md +++ b/content/tutorial-static_equilibrium.md @@ -78,7 +78,7 @@ This defines `forceA` as being a vector with magnitude of 1 in the $x$ direction It may be helpful to visualize these forces in order to better understand how they interact with each other. Matplotlib is a library with visualization tools that can be utilized for this purpose. -Quiver plots will be used to demonstrate [three dimensional vectors](https://matplotlib.org/3.3.4/gallery/mplot3d/quiver3d.html), but the library can also be used for [two dimensional demonstrations](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.quiver.html). +Quiver plots will be used to demonstrate [three dimensional vectors](https://matplotlib.org/gallery/mplot3d/quiver3d.html), but the library can also be used for [two dimensional demonstrations](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.quiver.html). ```{code-cell} fig = plt.figure() diff --git a/site/contributing.md b/site/contributing.md index 9fd31d4b..78caf34e 100644 --- a/site/contributing.md +++ b/site/contributing.md @@ -1,114 +1,2 @@ -# 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://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 author `MyST` notebooks in jupyterlab, check out the -[jupyterlab_myst](https://mystmd.org/guide/quickstart-jupyter-lab-myst) extension! - -## 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. - -### 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 +```{include} ../CONTRIBUTING.md +```