Notebooks

A notebook is a page. smalldocs shows the outputs that were saved in it, and runs no code.

This page is a Jupyter notebook, docs/guide/notebooks.ipynb. smalldocs reads the cells of the notebook and the outputs that were saved in it. It does not start a kernel, which is the program that runs the code. So the page shows what the notebook showed when it last ran.

Text and printed output

words = "smalldocs reads the outputs a notebook was saved with".split()
for w in words[:4]:
    print(w.upper())

SMALLDOCS
READS
THE
OUTPUTS

Rich output

An output can hold the same result in several formats. smalldocs shows the first format that it can show, in this order:

HTML
SVG, PNG and JPEG pictures
Markdown, LaTeX and plain text

smalldocs shows a Markdown output as Markdown:

from IPython.display import Markdown
Markdown("**Bold** Markdown, from a cell's output")

Bold Markdown, from a cell’s output

An HTML output goes into the page unchanged, for example a table from pandas. The option #| echo: false hides the code of the next cell:

Page	Kind
index.qmd	Markdown with additions
notes.md	Markdown
this.ipynb	Notebook

The page keeps a picture from an output:

gradient()  # a picture, saved in the notebook as a PNG

Errors

An error shows its traceback. smalldocs removes the colour codes of the terminal from it:

1 / 0

---------------------------------------------------------------------------
ZeroDivisionError                         Traceback (most recent call last)
Cell In[5], line 1
----> 1 1 / 0
ZeroDivisionError: division by zero

Cell options

A code cell can start with option lines that begin with #|. smalldocs reads these options:

#| echo: false hides the code.
#| output: false hides the output.
#| include: false hides the code and the output.

A cell can also have tags, labels in its metadata that Jupyter lets you set. The tags remove-cell, remove-input and remove-output hide the same parts.