Contributing new notebooks#
The sources for all these notebooks are the Python scripts in the python
directory. The notebook files are generated from them with the gen-nb
script
(which requires p2j
). Do not edit the notebooks directly; instead edit the
Python scripts and regenerate the notebooks by running gen-nb
.
The notebooks are now deployed as html pages using jupyterbook tool. To make changes to the notebooks, make changes to the corresponding python files in examples/python
and then use the gen-nb
script to generate the notebook files.
Currently some notebooks are excluded from execution. See the examples/_config.yml
file. These notebooks are still deployed as html pages but they are not in executed form.
The check-examples
script (which is run regularly on the CI and can also be
run locally) first checks that the notebooks match what is generated by p2j
from the Python scripts; and then attempts to run all the scripts. For those
scripts that require credentials, it first tries to load them, and skips the
test if it fails. For those that require containers to be running, it first
tries to start them, and skips the test if it fails.
To add a new script, you can either create the Python file and convert it using
gen-nb
or create a notebook file, convert it to Python using p2j -r
, and
then run gen-nb
to convert back. In either case, please check that the
formatting in the notebook is satisfactory. Then add the name of the new
notebook to maintained-notebooks.txt
. If the new script requires special
set-up, such as local credentials, make sure it is covered by the checks in
check-examples
.