Console commands added by the nbdev library

nbdev comes with the following commands. To use any of them, you must be in one of the subfolders of your project: they will search for the settings.ini recursively in the parent directory but need to access it to be able to work. Their names all begin by nbdev so you can easily get a list with tab completion.

nbdev_build_lib[source]

nbdev_build_lib(fname:"A notebook name or glob to convert"=None)

Export notebooks matching fname to python modules

By default (fname left to None), the whole library is built from the notebooks in the lib_folder set in your settings.ini.

nbdev_update_lib[source]

nbdev_update_lib(fname:"A notebook name or glob to convert"=None)

Propagates any change in the modules matching fname to the notebooks that created them

By default (fname left to None), the whole library is treated. Note that this tool is only designed for small changes such as typo or small bug fixes. You can't add new cells in notebook from the library.

nbdev_diff_nbs[source]

nbdev_diff_nbs()

Prints the diff between an export of the library in notebooks and the actual modules

Extracting tests

nbdev_test_nbs[source]

nbdev_test_nbs(fname:"A notebook name or glob to convert"=None, flags:"Space separated list of flags"=None, n_workers:"Number of workers to use"=None, verbose:"Print errors along the way"=True, timing:"Timing each notebook to see the ones are slow"=False)

Test in parallel the notebooks matching fname, passing along flags

By default (fname left to None), the whole library is tested from the notebooks in the lib_folder set in your settings.ini.

Building documentation

The following functions complete the ones in export2html to fully build the documentation of your library.

make_readme[source]

make_readme()

Convert the index notebook to README.md

nbdev_build_docs[source]

nbdev_build_docs(fname:"A notebook name or glob to convert"=None, force_all:"Rebuild even notebooks that haven't changed"=False, mk_readme:"Also convert the index notebook to README"=True, n_workers:"Number of workers to use"=None)

Build the documentation by converting notebooks mathing fname to html

By default (fname left to None), the whole documentation is build from the notebooks in the lib_folder set in your settings.ini, only converting the ones that have been modified since the their corresponding html was last touched unless you pass force_all=True. The index is also converted to make the README file, unless you pass along mk_readme=False.

nbdev_nb2md[source]

nbdev_nb2md(fname:"A notebook file name to convert", dest:"The destination folder"='.', img_path:"Folder to export images to"='', jekyll:"To use jekyll metadata for your markdown file or not"=False)

Convert the notebook in fname to a markdown file

nbdev_detach[source]

nbdev_detach(path_nb:"Path to notebook", dest:"Destination folder"='', use_img:"Convert markdown images to img tags"=False)

Export cell attachments to dest and update references

Other utils

nbdev_read_nbs[source]

nbdev_read_nbs(fname:"A notebook name or glob to convert"=None)

Check all notebooks matching fname can be opened

By default (fname left to None), the all the notebooks in lib_folder are checked.

nbdev_trust_nbs[source]

nbdev_trust_nbs(fname:"A notebook name or glob to convert"=None, force_all:"Trust even notebooks that haven't changed"=False)

Trust noteboks matching fname

By default (fname left to None), the all the notebooks in lib_folder are trusted. To speed things up, only the ones touched since the last time this command was run are trusted unless you pass along force_all=True.

nbdev_fix_merge[source]

nbdev_fix_merge(fname:"A notebook filename to fix", fast:"Fast fix: automatically fix the merge conflicts in outputs or metadata"=True, trust_us:"Use local outputs/metadata when fast mergning"=True)

Fix merge conflicts in notebook fname

When you have merge conflicts after a git pull, the notebook file will be broken and won't open in jupyter notebook anymore. This command fixes this by changing the notebook to a proper json file again and add markdown cells to signal the conflict, you just have to open that notebook again and look for >>>>>>> to see those conflicts and manually fix them. The old broken file is copied with a .ipynb.bak extension, so is still accessible in case the merge wasn't sucessful.

Moreover, if fast=True, conflicts in outputs and metadata will automatically be fixed by using the local version if trust_us=True, the remote one if trust_us=False. With this option, it's very likely you won't have anything to do, unless there is a real conflict.

bump_version[source]

bump_version(version, part=2)

test_eq(bump_version('0.1.1'   ), '0.1.2')
test_eq(bump_version('0.1.1', 1), '0.2.0')

nbdev_bump_version[source]

nbdev_bump_version(part:"Part of version to bump"=2)

Increment version in settings.py by one

Git hooks

nbdev_install_git_hooks[source]

nbdev_install_git_hooks()

Install git hooks to clean/trust notebooks automatically

This command installs git hooks to make sure notebooks are cleaned before you commit them to GitHub and automatically trusted at each merge. To be more specific, this creates:

  • an executable '.git/hooks/post-merge' file that contains the command nbdev_trust_nbs
  • a .gitconfig file that uses nbev_clean_nbs has a filter/diff on all notebook files inside nbs_folder and a .gitattributes file generated in this folder (copy this file in other folders where you might have notebooks you want cleaned as well)

Starting a new project

nbdev_new[source]

nbdev_new(name:"A directory to create the project in")

Create a new nbdev project with a given name.

nbdev_new is a command line tool that creates a new nbdev project based on the nbdev_template repo. It'll initialize a new git repository and commit the new project.

After you run nbdev_new, please edit settings.ini and run nbdev_build_lib.

Export