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 <https://jupytext.readthedocs.io/en/latest/>`_.
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 <https://myst-nb.readthedocs.io/en/latest/index.html>`_.

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 <https://myst-nb.readthedocs.io/en/latest/index.html>`_.

In the future, if there is a need for notebooks under ``examples``,
one could use the package `nbmake <https://github.com/treebeardtech/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``.