Contributing#

We very much welcome contributions! If you have an idea or proposal for a new tutorial, please open an issue 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 notebooks. These notebooks are used to produce static websites and can be opened as notebooks in Jupyter using Jupytext.

Note: You should use CommonMark markdown cells. Jupyter only renders CommonMark.

Why Jupyter Notebooks?#

The choice of Jupyter Notebook in this repo instead of the usual format (reStructuredText) 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, 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 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.

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:

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.