Introduction to nbdev

How to use the nbdev format
Lesson 7

Lesson Video:

Introduction

A library to build libraries out of Jupyter Notebooks.

I personally have mixed emotions with this. I’m of the fan of not everything should be done in notebooks, and there are specific reasons why and how if done properly it could be used.

In the hopes of ensuring that the fastai codebase doesn’t look foreign to you, this section will cover some basics of nbdev by showcasing their capabilities (such as did you know this whole course was built on it!)

Basic Premise

The central idea is that, as mentioned earlier, every step of the software development cycle is performed in the notebook. This includes documentation, testing, and source code writing.

They rely on directives, which are “tags” that we can apply some special functionality to a certain cell when nbdev processes it. The main ones I utilize:

  • default_exp: The name of the exported module
  • export: Specifying the contents of a cell should be sent to the .py
  • exports: The contents should be exported and the source code shown
  • hide: Don’t show this code in the documentation
  • echo: false: Hide the output from running this cell

They are added as comments into the notebook in a code cell (for nbdev specific ones) such as:

#| default_exp
my_module_name

What you will see now is the output from creating such a cell that has export and exports.

The code used was:

def addition(a,b):
    "Add two numbers together"
    return a+b

addition

 addition (a, b)

Add two numbers together

def subtraction(a,b):
    "Subtracts two numbers"
    return a-b

subtraction

 subtraction (a, b)

Subtracts two numbers

You can see that export shows the autogenerated notebook documentation while exports shows the documentation and the source code to our function.

Using these methods we can quickly create modules and libraries for our code

Some bad habits

  • Using @patch to save lines of code
  • Minimizing lines of code in general
  • Not utilizing the docstring fully

All of these are discussed throughly in my upcoming courses. I would not recommend studying the fastai source code closely if you are learning coding and want to have clean code that you can show others in the future.

I also do not personally code in Jupyter Notebooks anymore, everything is done in Visual Studio Code. However there are use cases for when using nbdev could be viable such as small projects or this where I’m utilizing it and Quarto to build this course.

After this lesson I will be doing some streams to showcase nbdev-extensions which empowers this course and introducing how extensions can be made for nbdev