Quickstart¶
The aim of this quickstart is to help you get up to speed with notabene
.
You can either introduce notabene
to an existing or a new project.
Below we will describe what is a common workflow for using notabene
.
Installing the Library¶
You can use pip to install notabene-cli
.
pip install notabene-cli
Preparing your repository¶
Create a (possibly empty) pyproject.toml
file in the root of your project.
For now, it is fine if this file is empty, if you don’t have any other tools interacting with it. An example of what the directory structure of your repository could look like after adding this file is:
my-project-folder
├── config
│ └── settings.py
├── notebooks
│ ├── my-exploratory-data-analysis.ipynb
│ └── my-deep-learning-research.ipynb
├── requirements.txt
└── pyproject.toml
Note
What is this pyproject.toml file?
The pyproject.toml
file is very common file for configuring tools in python projects.
By using a single file, cluttering from configuration tools is limited.
If you would like to know more about this file you can read the following page from the Python Packaging Authoroty.
Note
How does NotaBene use the pyproject.toml file?
NotaBene uses the pyproject.toml
file to determine the root of your repository.
All commands will be executed relative to this repository root.
If you don’t want to use this file, then all commands have the ability insert a root to execute the commands from using arguments. However, for you own sake, peace of mind and ease of use I would recommend against that.
NotaBene Templates¶
Currently, notabene
has a set of commands helping you to create and use notebook templates.
Creating a new template¶
To create a new template from an existing notebook named your-notebook.ipynb
, run:
notabene template create <your-notebook.ipynb>
Using an existing template¶
To make use of an existing template to create a new notebook named your-notebook.ipynb
, run:
notabene template use <your-notebook.ipynb>
Quality check all notebooks¶
Quality check all notebooks to make sure they all respect at least one of your templates. Will fail if a notebook is found that does not respect any notebooks. A common use-case is to include this step in your git project as a quality check for merge requests. (GitLab CICD, Github Actions)
notabene template check
List the registered notebooks¶
Show a list of the templates you registered in this project.
notabene template list