Adding Jupyter Notebooks

Here we explain how to add jupyter notebooks to the repository.

Notebooks as percent files

By default jupyter notebooks are saved as json files with .ipynb extension. These have two drawbacks:

• json files are hard to put under version control using git,

• editing notebook files directly in a text editor is cumbersome.

The solution to this is to use an alternative format.

We use the percent format of jupytext. The file extension is .pct.py.

In this format the notebook is stored as a valid python file. Cell information is stored in the comments. Using this format we can modify code cells as well as markdown cells directly in a text editor.

Of course in this format, only the input cells are stored. The cell output and the notebook state are ignored.

To open a percent file from the web interface of jupyter, one has to Right click on the file -> Open With -> Jupytext.

Use notebooks in documentation

Notebooks under docs/source will be converted to html by myst-nb.

Notebooks get executed before getting rendered to html. This means the outputs (including the widgets) get exported as well!

Testing

For now the only notebooks in the repository are under docs/source, so they get executed by myst-nb.

In the future, if there is a need for notebooks under examples, one could use the package nbmake with pytest.

For snapshot tests on rich output of cells, one could use syrupy along with the screenshot functionality of widgets when available.

Style and formating

Like with Blender examples, we generally want notebook files to be excluded from style checks related to imports since import will generally not be at the top of the file.

One can achieve this by adding the notbook file to the list of exceptions in the files pyproject.toml and .flake8.