Notebooks

What is a notebook?

Notebooks allow you to mix code, output (including figures), and text in a single document, and are often used for data analysis and other forms of numerical computing. Notebooks are generally edited in a browser, using the JupyterLab or Jupyter Notebook browser apps, or in R Markdown, which is part of R Studio.

The downside of this workflow is that these apps do not (yet) support all of the features of a modern code editor. In addition, many people prefer to work with plain-text code. Therefore, Rapunzel provides most of the functionality of a traditional notebook while still preserving the flexibility of a regular plain-text code editor.

Defining Markdown, code, and output cells

A Markdown (or: comment) cell contains comments. A code cell contains a chunk of code that should be executed together. An output cell contains the output that was generated by a code cell. You can define cells in two ways, differing only in the syntax for the Markdown cell.

Python

Python (but not R) supports multiline-strings using the """ syntax. Such multiline strings are interpreted as Markdown cells. Code in-between Markdown cells is interpreted as code cells. Comments preceded by an # % output line are interpreted as output cells.

"""
# Markdown heading

This is a Markdown cell.
"""

print('Hello!')  # This is a code cell that generates the output cell below

# % output
# Hello!
# 

Exporting the script above to .html gives the following result:

Figure 1. Markdown, code, and output cells exported to .html.

Python and R

Since R does not support multiline-strings, you can also define Markdown cells by starting a comment block with an # %% line. Code in-between Markdown cells is interpreted as code cells. Comments preceded by an # % output line are interpreted as output cells.

# %%
# # Markdown heading
#
# This is a Markdown cell.

print('Hello!')  # This is a code cell that generates the output cell below

# % output
# [1] "Hello!"
# 

Capturing image output

There are two ways to capture image output. The first way, called 'Capture images as code annotations' under Preferences, puts the images as annotations next to the code that generated them:

Figure 2. Image annotations.

The second way, called 'Capture images and text as code annotations and comments' under Preferences, puts images as annotations next to the output cell that was generated while executing code cells. When exporting to .html or other formats, these images will be included.

Figure 3. Image annotations combined with output capture.

Importing and exporting

You can import from, and export to Jupyter Notebook (.ipynb) format. Comment, code, and output cells are all preserved, including images, which are imported as image annotations.

You can export to .docx, .pdf, and .html format.