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?
lib2nbdevwill ask where you want your notebooks to be located. Generally we recommend answering with
nbs, so they all get placed in a
- Do I want to use
nbdev's default Github CI?
lib2nbdevcan 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>
fastreleaseallows for quick
condareleases, however you need to have a
setup.pythat'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.pywill live in the newly generated
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:
In your terminal.
from lib2nbdev.convert import convert_lib; convert_lib()
You will then see a series of questions pop up, similar to below. Answer them, as they will guide you through setting up your
Note: The name of your library should point to the source folder of your project.
lib2nbdev 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.ymlto 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.
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).