Intro to Notebook Templates

Creating a Notebook Template

Both ipynb and py file types are supported for use as templates.

To create a Notebook Template, we use a tool called jupytext. It allows for interchangeably converting between .ipynb and .py files.

If you would like to convert an existing .ipynb file to create a template in .py form you can either follow the instructions for installation on their homepage, or use convert_ipynb_to_py directly from the console when Notebooker is installed.

The purpose of a notebook template is to allow you to write Jupyter notebooks as normal, and then commit them into source control as python files: allowing for simple diffs and control over how notebooks are promoted into the live Notebooker environment for execution.

Where should templates go?

It is possible (and encouraged) to use a separate git repository version controlling notebook templates. To use a git repository as a notebook templates repository, you simply need to create a folder called notebook_templates/ which contains the .py and .ipynb template files. Additionally, a notebook_requirements.txt, containing extra package requirements to be installed, should be added to that folder.

For Notebooker to use your checked-out repository, set two command-line parameters:

  • Set --py-template-base-dir to the checked-out repository

  • Set --py-template-subdir to the subdirectory within your git repo which contains the templates

Adding parameters

By adding parameters to your jupyter notebooks, Notebooker allows you to turn your notebooks from static reports into dynamically-generated templates. For example, if you want to run a notebook for every G10 currency, it is possible to write one report and run it with 10 different parameters.

To add a parameter, create a cell with the tag “parameters” which contains all of the static parameters which you’d like to be able to parametrize. It’s that simple! For more information, see the readme within papermill’s documentation.

Testing Notebook Templates

If you’d like, it’s possible to set up tests for your notebook templates using a 3rd party CI tool such as Jenkins. Two tools are provided as command line entrypoints for template testing and verification:

  • notebooker_template_sanity_test - A quick test to ensure that the notebook templates are formatted correctly.

  • notebooker_template_regression_test - A longer test to ensure that the notebook templates can all be executed with their default parameters.