Converting A Library (Tutorial)

Learn how to use lib2nbdev2 to convert your existing Python libraries to nbdev ones

Installing lib2nbdev2

Before utilizing lib2nbdev2, you should install it on your system. Currently there only pip releases available.

The library also requires at least python 3.7

With pip

To install with pip, run:

pip install lib2nbdev2

(or pip3 depending on your setup)

Setting Up Your Repository, Things You Should Be Thinking About

When converting your library, the end result will look very similar to other nbdev-created libraries, such as this one or the fastai library. This being your repository will have a place for your notebooks, a settings.ini file, and potential Github actions.

Before converting your library, you should consider:

• Where do I want my notebooks to be stored? > lib2nbdev2 will ask where you want your notebooks to be located. Generally we recommend answering with nbs, so they all get placed in a nbs folder

The Conversion Process

Converting any library to the nbdev format is extremely simple. From your linux CLI, go to the home directory of your existing repository or library, and run:

convert_lib

In your terminal.

You will then see a series of questions pop up, similar to below. Answer them, as they will guide you through setting up your settings.ini:

Note: The name of your library should point to the source folder of your project.

Afterwards lib2nbdev2 will convert your .py files into notebooks and store them away in wherever you specified:

Finally you will be prompted as to whether you want to use the nbdev Github workflow template. > Notice: If you choose yes (1), you should make sure to explicitly add the workflow located in .github/workflows/main.yml to git on your next commit

And you are done! Your entire library has been converted into Jupyter Notebooks, and you are now setup to work with the nbdev workflow. When modifying the library you should be working directly out of those Jupyter Notebooks, and be making new ones as you progress.

Closing Remarks

It should be noted that these are blank notebook templates, so you should modify the opening headers and descriptions that are autogenerated in each notebook with a relevant title.

Also, if you want to use nbdev generated documentation, you should think about how to bring in your existing documentation and tutorials into these notebooks. You can also just link directly to your existing Markdown files by adjusting the sidebar.json located in the _docs folder. (You need to run nbdev_build_docs at least once for this to show up).