Margo: Margin Notes for Computational Notebooks

Abstract

Jupyter Notebooks combine prose, code and execution output, making them a popular choice over plain source code for communicating computational methods. However, notebooks cannot be reused as modules, and the recommended practice of writing module code in plain source files forces developers to abandon the notebook format. This thesis offers the rationale, design, and implementation details for a system for importing Jupyter Notebooks as Python modules. One challenge we face is that notebook code is written differently from module code — Jupyter Notebooks often include non-reusable code. Therefore, we must be able to define a module view for a notebook that excludes particular cells. To solve this, we develop a scheme of specially formed code comments. We call these comments “margin notes,” and we develop a flexible syntax for margin notes called “Margo.” The margin note system opens up additional ways to extend notebooks. Two specific applications that leverage Margo notes extensively are presented as exemplars: A command line tool to define arbitrary interfaces into notebooks for applications such as pip and GNU Make; and a notebook editor UI concept that supports hierarchical cell relationships.