Create delightful python projects using Jupyter Notebooks
nbdev is a library that allows you to develop a python library in Jupyter Notebooks, putting all your code, tests and documentation in one place. That is: you now have a true literate programming environment, as envisioned by Donald Knuth back in 1983!
nbdev makes debugging and refactoring your code much easier relative to traditional programming environments. Furthermore, using nbdev promotes software engineering best practices because tests and documentation are first class citizens.
The developers use this regularly on macOS and Linux. We have not tested it on Windows and not all features may work correctly.
nbdev provides the following tools for developers:
__all__(more details) with your exported functions, classes, and variables.
For example, lets define a class that represents a playing card, with associated docs and tests in a Jupyter Notebook:
In the above screenshot, we have code, tests and documentation in one context!
nbdev renders this into searchable docs (which are optionally hosted for free on GitHub Pages). Below is an annotated screenshot of the generated docs for further explanation:
H1heading in a notebook with a note block API Details as the summary.
nbdevautomatically renders a Table of Contents for you.
nbdevautomatically renders the signature of your class or function as a heading.
Cardclass is defined immediately above, however this works across pages and modules. We will see another example of this in later steps.
nbdev is on PyPI and conda so you can just run
pip install nbdev or
conda install -c fastai nbdev. Microsoft Windows users should use
pip instead of
conda to install nbdev.
For an editable install, use the following:
git clone https://github.com/fastai/nbdev pip install -e nbdev
nbdev is tested to work on Ubuntu, Macos and Windows, for the versions tagged with the
-latest suffix in these docs.
nbdev must be installed into the same python environment that you use for both your Jupyter Server and your workspace.
The following are helpful resources for getting started with nbdev:
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, the fastai project strives to abide by generally accepted best practices in open-source software development.
Make sure you have the git hooks we use installed by running
in the cloned repository folder.
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.
nbdev has been used to build innovative software used by many developers, such as fastai, a deep learning library which implements a unique layered api and callback system, and fastcore, an extension to the Python programming language. 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.
Here, for instance, is how
combined_cos is defined and documented in the