Package: nbdev
Getting StartedNB: This is nbdev v2, a major upgrade of nbdev. Whilst the differences
to nbdev1 aren’t huge, it does require some changes. The old version
docs are atnbdev1.fast.ai. You can use
version-pinning insettings.ini(i.e'nbdev<2') to stop nbdev from
upgrading. To upgrade, follow themigration
tutorial.nbdevis a notebook-driven development platform. Simply write
notebooks with lightweight markup and get high-quality documentation,
tests, continuous integration, and packaging for free!nbdevmakes debugging and refactoring your code much easier than in
traditional programming environments since you always have live objects
at your fingertips.nbdevalso promotes software engineering best
practices because tests and documentation are first class.Documentationis automatically generated usingQuartoand hosted onGitHub
Pages. Docs support LaTeX, are searchable,
and are automatically hyperlinked (including out-of-the-box support
for many packages vianbdev-index)Publish packages to PyPI and condaas 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 codeallowing
you to use your IDE for code navigation or quick editsTestswritten as ordinary notebook cells are run in parallel with
a single commandContinuous integrationout-of-the-box withGitHub
Actionsthat run your tests and
rebuild your docsGit-friendly notebookswithJupyter/Git
hooksthat
clean unwanted metadata and render merge conflicts in a human-readable
format… and much more!Installnbdev works on macOS, Linux, and most Unix-style operating systems. It
works on Windows under WSL, but not under cmd or Powershell.You can install nbdev with pip:pipinstallnbdev… or with conda (or mamba):condainstall-cfastainbdevNote thatnbdevmust be installed into the same Python environment
that you use for both Jupyter and your project.How to use nbdevThe best way to learn how to use nbdev is to complete either thewritten walkthroughor
video walkthrough:Alternatively, there’s ashortened version of the video
walkthroughwith coding sections sped up
using theunsilencePython library – it’s 27 minutes faster, but a bit
harder to follow.You can also runnbdev_helpfrom the terminal to see the full list of
available commands:!nbdev_helpnbdev_bump_version              Increment version in settings.ini by one
nbdev_changelog                 Create a CHANGELOG.md file from closed and labeled GitHub issues
nbdev_clean                     Clean all notebooks in `fname` to avoid merge conflicts
nbdev_conda                     Create a `meta.yaml` file ready to be built into a package, and optionally build and upload it
nbdev_create_config             Create a config file.
nbdev_deploy                    Deploy docs to GitHub Pages
nbdev_docs                      Create Quarto docs and README.md
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_help                      Show help for all console scripts
nbdev_install                   Install Quarto and the current library
nbdev_install_hooks             Install Jupyter and git hooks to automatically clean, trust, and fix merge conflicts in notebooks
nbdev_install_quarto            Install latest Quarto on macOS or Linux, prints instructions for Windows
nbdev_merge                     Git merge driver for notebooks
nbdev_migrate                   Convert all directives and callouts in `fname` from v1 to v2
nbdev_new                       Create an nbdev project.
nbdev_prepare                   Export, test, and clean notebooks, and render README if needed
nbdev_preview                   Preview docs locally
nbdev_proc_nbs                  Process notebooks in `path` for docs rendering
nbdev_pypi                      Create and upload Python package to PyPI
nbdev_readme                    None
nbdev_release_both              Release both conda and PyPI packages
nbdev_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 version
nbdev_sidebar                   Create sidebar.yml
nbdev_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 themFAQQ: What is the warning “Found a cell containing mix of imports and computations. Please use separate cells”?A: You should not have cells that are not exported,andcontain a mix
ofimportstatements along with other code. For instance, don’t do
this 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 up
to date, by running the imports, exported cells, andshow_docfunctions
in your notebooks. When you mix imports with other code, that other code
will be run too, which can cause errors (or at least slowdowns) when
creating your website.Q: Why is nbdev asking for root access? How do I install Quarto without root access?A: When you setup your first project, nbdev will attempt to
automatically download and installQuartofor
you. This is the program that we use to create your documentation
website.Quarto’s standard installation process requires root access, and nbdev
will therefore ask for your root password during installation. For most
people, this will work fine and everything will be handled automatically
– if so, you can skip over the rest of this section, which talks about
installing without root access.If you need to install Quarto without root access on Linux, firstcdto wherever you want to store it, thendownload
Quarto, and type:dpkg-xquarto*.deb.
mvopt/quarto./
rmdiropt
mkdir-p~/.local/bin
ln-s"$(pwd)"/quarto/bin/quarto~/.local/binTo use this non-root version of Quarto, you’ll need~/.local/binin
yourPATHenvironment
variable.
(Alternatively, change theln -sstep to place the symlink somewhere
else in your path.)Q: Someone told me not to use notebooks for “serious” software development!A:Watch this video. Don’t worry, we
still get this too, despite having usednbdevfor a wide range of
“very serious” software projects over the last three years, includingdeep learning libraries,API
clients,Python language
extensions,terminal user
interfaces, and more!ContributingIf you want to contribute tonbdev, be sure to review thecontributions
guidelines.
This project adheres to fastai’scode 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 havenbdev’s git hooks installed by runningnbdev_install_hooksin the cloned repository.CopyrightCopyright © 2019 onward 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.