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.
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.
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.
Sphinx is configured with the appropriate extensions to execute the notebooks and generated webpages from them. To accomplish this from a fresh repo:
-
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
-
Build and view
make html && <your_browser> _build/html/index.html
If you have your own tutorial in the form of a Jupyter notebook and you'd like to try it out on the site:
- Add your notebook to the
content/
directory - Update
content/requirements.txt
with the dependencies for your tutorial - Update the
toctree
inindex.rst
to include your new entry - Update the attribution section (below) to credit the original tutorial author.
- 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.