An example site for creating web-based NumPy tutorials from Jupyter Notebooks

This is a minimal example of how one could set up a repository for generating tutorials from user-submitted Jupyter notebooks. Note that this is only one possible such configuration, and is only intended for demonstration/discussion purposes.

Motivation

The purpose here is to investigate the feasibility of a tutorial-generation mechanism based on Jupyter notebooks:

• Jupyter notebooks are a common format for communicating scientific information.
• rST may present a barrier for some people who might otherwise be very interested in contributing tutorial material.

This repo also serves as a test-bed for various workflow components.

Example tutorial

To demonstrate the auto-generation of web content from Jupyter notebook source files, a tutorial already in Jupyter notebook form was needed. I grabbed this CS231n tutorial which is linked from numpy.org.

Modifying tutorials

The only modification made to the tutorial was to add a raises-exception tag to a single cell. This is a feature of MyST-NB to prevent the execution kernel from halting when a cell in a notebook raises an expected exception (e.g. for demonstration purposes). Other features, such as hiding code cells, inputs, outputs, etc. are available.

Generating the "site"

Sphinx is configured with the appropriate extensions to execute the notebooks and generated webpages from them. To accomplish this from a fresh repo:

1. Install the dependencies:

   pip install -r requirements.txt
   

   To execute the notebooks, you'll also need to install the dependencies for the tutorial(s) themselves:

   pip install -r content/requirements.txt
   

2. Build and view

   make html && <your_browser> _build/html/index.html
   

Adding your own tutorials

If you have your own tutorial in the form of a Jupyter notebook and you'd like to try it out on the site:

1. Add your notebook to the content/ directory
2. Update content/requirements.txt with the dependencies for your tutorial
3. Update the toctree in index.rst to include your new entry
4. Update the attribution section (below) to credit the original tutorial author.

Attribution

• The cs231n tutorial is by @jcjohnson. The full tutorial in its original form is linked via numpy.org.
• The SVD tutorial is by @melissawm. The full tutorial is available via the tutorials page of the official NumPy documentation.