nbdev 2.0.1

Create delightful software with Jupyter Notebooks

Getting started

nbdev is a system for exploratory programming. Simply write notebooks with lightweight markup and get high-quality documentation, tests, continuous integration, and packaging for free!

nbdev makes debugging and refactoring your code much easier than in traditional programming environments since you always have live objects at your fingertips. nbdev also promotes software engineering best practices because tests and documentation are first class.

• Documentation is automatically generated using Quarto and hosted on GitHub Pages. Docs support LaTeX, are searchable, and are automatically hyperlinked (including out-of-the-box support for many packages via nbdev-index). You also have fine-grained control over how cells are displayed.
• Publish packages to PyPI and conda as well as tools to simplify package releases. Python best practices are automatically followed, for example, only exported objects are included in __all__
• Two-way sync between notebooks and plaintext source code allowing you to use your IDE for code navigation or quick edits.
• Tests written as ordinary notebook cells are run in parallel with a single command. You have fine-grained control over which tests are run.
• Continuous integration out-of-the-box with GitHub Actions that run your tests on each push and rebuild docs on each merge.
• Git-friendly notebooks with tools that clean unwanted metadata and render merge conflicts in a human-readable format.
• … and much more! See the Getting Started section below for more.

Install

With pip:

pip install nbdev

With conda:

conda install -c fastai nbdev

Note that nbdev must be installed into the same Python environment that you use for both Jupyter and your project.

Getting started

We suggest these helpful resources to get started with nbdev:

• Official tutorial; (we suggest replicating each step to solidify your understanding)
• Official documentation.

You can run nbdev_help from the terminal to see the full list of available commands:

!nbdev_help

nbdev_bump_version              Increment version in settings.ini by one
nbdev_clean                     Clean all notebooks in `fname` to avoid merge conflicts
nbdev_conda                     Create and upload a conda package
nbdev_create_config             Create a config file
nbdev_deploy                    Deploy docs to GitHub Pages
nbdev_docs                      Generate docs
nbdev_export                    Export notebooks in `path` to Python modules
nbdev_filter                    A notebook filter for Quarto
nbdev_fix                       Create working notebook from conflicted notebook `nbname`
nbdev_ghp_deploy                Deploy docs in `doc_path` from settings.ini to GitHub Pages
nbdev_help                      Show help for all console scripts
nbdev_install                   Install Quarto and the current library
nbdev_install_hooks             Install git hooks to clean and trust notebooks automatically
nbdev_install_quarto            Install latest Quarto on macOS or Linux, prints instructions for Windows
nbdev_migrate_directives        Convert all directives in `fname` from v1 to v2
nbdev_new                       Create a new project from the current git repo
nbdev_prepare                   Export, test, and clean notebooks
nbdev_preview                   Start a local docs webserver
nbdev_pypi                      Create and upload Python package to PyPI
nbdev_quarto                    Create Quarto docs and README.md
nbdev_release                   Release both conda and PyPI packages
nbdev_sidebar                   Create sidebar.yml
nbdev_test                      Test in parallel notebooks matching `fname`, passing along `flags`
nbdev_trust                     Trust notebooks matching `fname`
nbdev_update                    Propagate change in modules matching `fname` to notebooks that created them

FAQ

Q: Someone told me not to use notebooks for “serious” software development!

Watch this video. Don’t worry, we still get this too, despite having used nbdev for a wide range of “very serious” software projects over the last three years, including deep learning libraries, API clients, Python language extensions, terminal user interfaces, and more!

nbdev in the wild

fastai ecosystem

nbdev has been used to build innovative software in the fastai ecosystem, including the fastai deep learning library which implements a unique layered API and callback system, and fastcore, which supercharges Python leveraging its dynamic nature. Furthermore, nbdev allows a very small number of developers to maintain and grow a large ecosystem of software engineering, data science, machine learning, and devops tools.

Contributing

If you want to contribute to nbdev, be sure to review the contributions guidelines. This project adheres to fastai’s code of conduct. By participating, you are expected to uphold this code. In general, we strive to abide by generally accepted best practices in open-source software development.

Make sure you have nbdev’s git hooks installed by running nbdev_install_git_hooks in the cloned repository.

Copyright

Copyright 2019 onwards, fast.ai, Inc. Licensed under the Apache License, Version 2.0 (the “License”); you may not use this project’s files except in compliance with the License. A copy of the License is provided in the LICENSE file in this repository.