Learn how to use `lib2nbdev` to convert your existing Python libraries to `nbdev` ones
 

Installing lib2nbdev

Before utilizing lib2nbdev, you should install it on your system. Currently there are both conda and pip releases available.

The library also requires at least python 3.6

With pip

To install with pip, run:

pip install lib2nbdev

(or pip3 depending on your setup)

With conda

To install with conda, run:

conda install lib2nbdev

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?

    lib2nbdev 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

  • Do I want to use nbdev's default Github CI?

    lib2nbdev can generate a Github Actions CI for you to use specifically designed for nbdev. It will check that the notebooks were cleaned, there's no differences between the notebooks and the exported library, and that your tests all pass

  • Do I want to use fastrelease> fastrelease allows for quick pip and conda releases, however you need to have a setup.py that's similar to nbdev's. This will require manual adjustments after the library conversion process is over, as all the information needed for the setup.py will live in the newly generated settings.ini file

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:

image.png

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

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

image.png

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 image.png

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).