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.