Repository files navigation

nbdev is a notebook-driven development platform. Simply writenotebooks 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 intraditional programming environments since you always have live objectsat your fingertips.nbdev also promotes software engineering bestpractices because tests and documentation are first class.

• Documentation is automatically generated usingQuarto and hosted onGitHubPages. Docs support LaTeX, are searchable,and are automatically hyperlinked (including out-of-the-box supportfor many packages vianbdev-index)
• Publish packages to PyPI and conda as well as tools to simplifypackage 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 allowingyou to use your IDE for code navigation or quick edits
• Tests written as ordinary notebook cells are run in parallel witha single command
• Continuous integration out-of-the-box withGitHubActions that run your tests andrebuild your docs
• Git-friendly notebooks withJupyter/Githooks thatclean unwanted metadata and render merge conflicts in a human-readableformat
• … and much more!

nbdev works on macOS, Linux, and most Unix-style operating systems. Itworks on Windows under WSL, but not under cmd or Powershell.

You can install nbdev with pip:

pip install nbdev

… or with conda (or mamba):

conda install -c fastai nbdev

Note thatnbdev must be installed into the same Python environmentthat you use for both Jupyter and your project.

The best way to learn how to use nbdev is to complete either thewritten walkthrough orvideo walkthrough:

Alternatively, there’s ashortened version of the videowalkthrough with coding sections sped upusing theunsilence Python library – it’s 27 minutes faster, but a bitharder to follow.

You can also runnbdev_help from the terminal to see the full list ofavailable commands:

!nbdev_help

nbdev_bump_version        Increment version in settings.ini by onenbdev_changelog           Create a CHANGELOG.md file from closed and labeled GitHub issuesnbdev_clean               Clean all notebooks in `fname` to avoid merge conflictsnbdev_conda               Create a `meta.yaml` file ready to be built into a package, and optionally build and upload itnbdev_create_config       Create a config file.nbdev_docs                Create Quarto docs and README.mdnbdev_export              Export notebooks in `path` to Python modulesnbdev_filter              A notebook filter for Quartonbdev_fix                 Create working notebook from conflicted notebook `nbname`nbdev_help                Show help for all console scriptsnbdev_install             Install Quarto and the current librarynbdev_install_hooks       Install Jupyter and git hooks to automatically clean, trust, and fix merge conflicts in notebooksnbdev_install_quarto      Install latest Quarto on macOS or Linux, prints instructions for Windowsnbdev_merge               Git merge driver for notebooksnbdev_migrate             Convert all markdown and notebook files in `path` from v1 to v2nbdev_new                 Create an nbdev project.nbdev_prepare             Export, test, and clean notebooks, and render README if needednbdev_preview             Preview docs locallynbdev_proc_nbs            Process notebooks in `path` for docs renderingnbdev_pypi                Create and upload Python package to PyPInbdev_readme              Create README.md from readme_nb (index.ipynb by default)nbdev_release_both        Release both conda and PyPI packagesnbdev_release_gh          Calls `nbdev_changelog`, lets you edit the result, then pushes to git and calls `nbdev_release_git`nbdev_release_git         Tag and create a release in GitHub for the current versionnbdev_requirements        Writes a `requirements.txt` file to `directory` based on settings.ini.nbdev_sidebar             Create sidebar.ymlnbdev_test                Test in parallel notebooks matching `path`, passing along `flags`nbdev_trust               Trust notebooks matching `fname`nbdev_update              Propagate change in modules matching `fname` to notebooks that created themnbdev_update_license      Allows you to update the license of your project.

A: You should not have cells that are not exported,and contain a mixofimport statements along with other code. For instance, don’t dothis in a single cell:

importsome_modulesome_module.something()

Instead, split this into two cells, one which doesimport some_module,and the other which doessome_module.something().

The reason for this is that when we create your documentation website,we ensure that all of the signatures for functions you document are upto date, by running the imports, exported cells, andshow_doc functionsin your notebooks. When you mix imports with other code, that other codewill be run too, which can cause errors (or at least slowdowns) whencreating your website.

A: When you setup your first project, nbdev will attempt toautomatically download and installQuarto foryou. This is the program that we use to create your documentationwebsite.

Quarto’s standard installation process requires root access, and nbdevwill therefore ask for your root password during installation. For mostpeople, this will work fine and everything will be handled automatically– if so, you can skip over the rest of this section, which talks aboutinstalling without root access.

If you need to install Quarto without root access on Linux, firstcdto wherever you want to store it, thendownloadQuarto, and type:

dpkg -x quarto*.deb.mv opt/quarto ./rmdir optmkdir -p~/.local/binln -s"$(pwd)"/quarto/bin/quarto~/.local/bin

To use this non-root version of Quarto, you’ll need~/.local/bin inyourPATH environmentvariable.(Alternatively, change theln -s step to place the symlink somewhereelse in your path.)

A:Watch this video. Don’t worry, westill get this too, despite having usednbdev for a wide range of“very serious” software projects over the last three years, includingdeep learning libraries,APIclients,Python languageextensions,terminal userinterfaces, and more!

If you want to contribute tonbdev, be sure to review thecontributionsguidelines.This project adheres to fastai’scode ofconduct.By participating, you are expected to uphold this code. In general, westrive to abide by generally accepted best practices in open-sourcesoftware development.

Make sure you havenbdev’s git hooks installed by runningnbdev_install_hooksin the cloned repository.

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