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.

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