Executable Tutorials

A repository demonstrating one way to manage and distribute interactive tutorials. See the Guide to Contributing for a good overview of what this is like to use.

Demo Links

• Tutorials are written in MyST Markdown.
• Tutorials can be easily edited as notebooks in JupyterLab.
• Executed tutorials are published on a GitHub Pages site.
• Jupyter Lite (beta) (works only on the basic executable example so far, missing dependencies for others)
• Binder

Notes on the notebook file format

We do use MyST Markdown format for the notebooks, please visit the upstream documentation to learn more about the reasoning behind the choice. However, we add it here that you can easily have the same user experience in JupyterLab if these two dependencies are installed:

• jupytext library
• jupyterlab-myst JupyterLab extension

Goals

• Make content easy to explore and try in a variety of modes:
  • interactive and non-interactive
  • local and cloud-based
  • Jupyter and not-Jupyter
• Document an accessible development workflow, so that non-experts can contribute.
• Keep the infrastructure as simple as possible.

Build the site

There are currently two distinct technology stacks that support the executable-tutorials paradigm: a legacy sphinx-based static-site generation engine, and the newer [myst][myst-org] project. The executable-tutorials repo contains information about both development patterns, and endeavors to serve as a transition guide between technology stacks.

By default, the necessary tooling for both technology stacks is installed with pip install -r requirements.txt

Build with sphinx

make html

The static site can then be viewed by simply opening the index in any browser, for example::

firefox _build/html/index.html

Build with myst

myst start --execute

This will execute the notebooks, build the site, and set up a server for rendering the site. The rendered page can be viewed by opening localhost:3000 in a browser.

To Do

• Test execution of changed tutorials only in CI on PR.
• Set up devcontainer.
• Add example with additional dependencies.

Prior Art

Examples that this is drawing from:

• https://github.com/Caltech-IPAC/irsa-tutorials
• https://github.com/MotherDuck-Open-Source/sql-tutorial