CLI Documentation

This is the official documentation for the CLI version of pylabnotebook. All commands explained here have a corresponding function (see API), but I highly reccomend to run this package from the command line, as it was created for.

Installation

Pylabnotebook can be installed via pip in an isolated environment (suggested):

(.venv) $ pip install pylabnotebook

To check the installation:

(.venv) $ labnotebook --version

Warning

Whilst the python dependencies are automatically downloaded and installed, this package highly relies on git. Therefore, there are some git requirements that need to be fullfilled:

git version >= 2.40.1, otherwise some functionalities do not work
git author and git email set, otherwise the tool cannot create a notebook, as it checks for git author.

Create a notebook

To create a new notebook, in the root folder of the project (the one that has the .git folder), type this command:

(.venv) $ labnotebook create -n "my project"

A message that confirms the creation of the .labnotebook folder should appear on the console as stout.

Note

Remember to never change the name of .labnotebook folder or any file inside of it.

Update a notebook

Prior to export the final .html version of the notebook, you have to update the file inside .labnotebook folder through this command (from the root folder of the project):

(.venv) $ labnotebook update

This command will evaluate git history from the last commit stored in .labnotebook/config.json. This means that, if the git history has changed and the last commit in .labnotebook/config.json is not in the new git history, this will raise an error. To prevent this error, you could force labnotebook update to start from the beginning of git history through the -f/–force flag. After the update, a new commit with the changes in .labnotebook folder is created: this commit has labnotebook and labnotebook@email.com as author and email, respectively.

Link to analysis files

When updating the notebook, it automatically create a list of analysis files for each commit with direct links to them. By default, it takes all the .html files changed/added in that commit (not the deleted or renamed ones). If you want to add different extensions, you can update the .labnotebook config.json file by adding/removing extensions in the ANALYSIS_EXT variable. Each extension should be separated by a comma, as it is considered an array (eg. “ANALYSIS_EXT”: [‘.html’, ‘.txt’]): just type the extension, not wildcards or other special characters. Moreover, by creating a “.labignore” file, you can exclude some files/folders to be recognized as analysis files (as for a standard .gitignore file it will use wildcards).

Export an html notebook

To export the notebook as a single .html file, from the root of the project type:

(.venv) $ labnotebook export -o my_project.html

It will create a my_project.html file with the notebook. You can then share the notebook with peers.

Note

You can customize the style of your notebook by either edit style.css file in .labnotebook folder, or provide a custom.css file and reference it in .labnotebook/config.json file (as a path starting from the root of your project).