nbdev

Install nbdev using pip. Note that nbdev must be installed into the same Python environment used for both Jupyter and your project. It is supported on macOS, Linux, and most Unix-style operating systems. On Windows, use WSL (Windows Subsystem for Linux) rather than cmd or Powershell.

pip install nbdev

In nbdev3, configuration has moved from settings.ini to pyproject.toml following PEP 621. Project metadata lives in the [project] section, and nbdev-specific settings live in [tool.nbdev].

To migrate an existing project, run nbdev-migrate-config in your project root. This will automatically convert your settings.ini to pyproject.toml and update your GitHub Actions workflows. Your existing notebooks and code do not require changes.

To ensure documentation generation works correctly and efficiently, do not mix import statements with other code in non-exported cells.

Incorrect:

import some_module
some_module.something()

Correct: Split them into two separate cells:

import some_module

some_module.something()

Top-level statements like try: import blocks or imports inside function definitions are acceptable.

Directives are special comments starting with #| that control cell visibility in rendered documentation, how source code is generated from notebook cells, and cell execution for tests and docs.

nbdev supports all Quarto directives and provides its own additional directives.

Key Syntax Rules:

• All spellings are equivalent (e.g., #| default_exp: core, #| default_exp:core, and #| default_exp core are the same).
• A value of true is equivalent to no value (e.g., #| hide: true is the same as #| hide).
• Directives can be stored in cell metadata as a dictionary under an nbdev key: {"nbdev": {"hide": "true", "eval": "false"}}.
• When a directive appears in both a comment and metadata, the comment takes precedence.

nbdev uses Quarto to render documentation websites from two primary source types:

1. Jupyter Notebooks: The recommended medium. nbdev pre-processes notebooks (handling directives and front matter) and may execute certain cells to dynamically render API documentation.
2. Quarto Markdown (.qmd): Used for pages containing no code.

Key Concepts:

• Notebook Processor: Uses nbdev.processors and nbdev.process.NBProcessor to transform notebooks. It handles directives like #|hide and processes front matter.
• Processing Pipeline: Intermediate pre-processed files are saved in a _proc/ directory at the repo root. Use this directory to debug processing issues.
• Static Site: The final HTML/JS/CSS files are generated in the doc_path directory (defaulting to _docs/) as specified in pyproject.toml.

nbdev provides several hooks to improve the Jupyter-git workflow:

• nbdev_merge: A custom git merge driver that automatically fixes conflicting outputs and metadata during merge, pull, rebase, and stash, leaving remaining conflicts in a state that is still readable by Jupyter.
• nbdev_clean: A Jupyter hook (supported in Jupyter Notebook and Jupyter Lab) that runs nbdev-clean on save. It removes unwanted metadata (like execution counts) and cleans ids from default Python reprs to prevent noisy diffs.
• nbdev_trust: A git post-merge hook that runs nbdev-trust to automatically trust notebooks in the repository after a merge, enabling widgets without manual intervention.

Run nbdev-install-hooks to automate notebook maintenance. This command installs:

1. Jupyter Hooks: A pre_save_hook that automatically cleans notebooks whenever you save them in Jupyter Notebook or JupyterLab.
2. Git Merge Driver: Configures git to use nbdev-merge to resolve notebook conflicts.
3. Git Diff Driver: Configures git to use nbdev-diff-driver for notebook diffs.
4. Git Post-Merge Hook: Automatically runs nbdev-trust after a merge to ensure notebooks are signed.

Use the --globally flag to install these in your global git and jupyter configurations instead of the local repository.

To control what gets exported from your notebook to your Python library, use the following cell directives:

• #| export: Marks a cell (markdown or code) to be included in the module. Markdown cells marked this way contribute to the module docstring.
• #| exportd: Similar to export, but used specifically to ensure the cell is included in the module's content (often used for code cells that should be part of the module but might be handled differently by the processor).
• #| default_exp <name>: Sets the default name for the module if the notebook is being exported to the default location (the '#' key in the internal processor).

Note on Markdown: Markdown cells that start with # (a heading) are automatically collected into the module docstring by the ExportModuleProc processor.

If you need to bypass pre-commit checks, you have three options:

1. Skip a specific hook: Use the SKIP environment variable with the hook ID.
2. Skip all hooks for one commit: Use the --no-verify flag with git commit.
3. Uninstall pre-commit: Completely remove the hooks from your repository.

While nbdev is primarily developed in notebooks, you can use nbdev-update to propagate small fixes (like typos or minor bug fixes) made directly in .py modules back to their source notebooks.

Constraints:

• You cannot create new cells or reorder existing cells using this command.
• Your corrections must be limited to existing cell content.
• Exported .py files must contain cell IDs in the format # %% path/nb.ipynb #cell_id. If your exports lack these IDs, run nbdev-export first to regenerate them.