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-dirto the checked-out repositorySet
--py-template-subdirto 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.
