Jupyter Notebook Style Guide#

Motivation#

This style guide is meant for anyone writing documentation pages, tutorials, or workflows as Jupyter notebooks.

The purpose is to make notebooks easy to understand and readable, and to minimize the reader’s cognitive overload when switching between different notebooks.

Recommendations#

Saving notebooks#

  • Notebooks that are part of documentation get executed by Sphinx during the documentation build process. For such notebooks, avoid saving outputs before committing a notebook.

    • Use “Restart kernel and clear all outputs” before saving.

    • nb-clean can be used to do this automatically.

  • Notebooks that are under version control such as git should generally not be saved with outputs since they can grow quite large.

Document structure#

  • Typically each notebook should have a title, given by a “level 1” markdown heading.

  • Use markdown headings to define sections, subsections, etc., for easy navigation and readability.

  • Consider placing each heading (or even subheading) in a separate cell. This aids collapsability of section contents (available in recent versions of JupyterLab).

  • For long notebooks, follow well-established standards from scientific publications for documentation structure. For example, start with an introduction defining the scope, and outline the notebook contents in the last paragraph of the introduction, explaining briefly what each (sub)section’s purpose is.

Portability#

  • Avoid hard-coding file paths which would require users to download files into specific folders.

  • Use APIs, not file systems, to access data.

    • pooch is a good candidate when sample files are needed.

Formatting#

Markdown cells#

  • Place one sentence per line, i.e., add a linebreak after every full stop. While irrelevant for readability of the rendered cell, this aids in reading the markdown code and most importantly the diff when a notebook is under version control.

  • Do not break at a column limit. This leads to reflowing of paragraphs when edits are made and thus makes the diff hard to decipher.

Code cells#

  • Line lengths should be limited to avoid horizontal scroll bars when viewing documentation pages in a browser or in Jupyter.

    • A line length of 88 (default in black) seems to work well.

  • Automatic code formatting (such as black, yapf, or flake8) is recommended, but in some cases it may hurt readability, so no binding recommendation is made, i.e., exceptions are allowed.

    • jupyterlab-code-formatter is a useful tool for applying automatic formatting to individual cells or entire notebooks. Example config for black:

      {
    {
    "black": {
        "line_length": 88,
        "string_normalization": false
    },
    "preferences": {
        "default_formatter": {
            "python": ["black"],
        }
    }
}