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 with nbdev so you can easily get a list with tab completion.

• chisel_nbdev_build_docs builds the documentation from the notebooks
• chisel_nbdev_build_lib builds the library from the notebooks
• chisel_nbdev_bump_version increments version in settings.py by one
• chisel_nbdev_clean_nbs removes all superfluous metadata form the notebooks, to avoid merge conflicts
• chisel_nbdev_detach exports cell attachments to dest and updates references
• chisel_nbdev_diff_nbs gives you the diff between the notebooks and the exported library
• chisel_nbdev_fix_merge will fix merge conflicts in a notebook file
• chisel_nbdev_install_git_hooks installs the git hooks that use the last two command automatically on each commit/merge
• chisel_nbdev_nb2md converts a notebook to a markdown file
• chisel_nbdev_new creates a new nbdev project
• chisel_nbdev_read_nbs reads all notebooks to make sure none are broken
• chisel_nbdev_test_nbs runs tests in notebooks
• chisel_nbdev_trust_nbs trusts all notebooks (so that the HTML content is shown)
• chisel_nbdev_update_lib propagates any change in the library back to the notebooks

Navigating from notebooks to script and back

nbdev_build_lib[source]

nbdev_build_lib(fname:"A notebook name or glob to convert"=None, bare:"Omit nbdev annotation comments (may break some functionality)."=False, recursive:"Search directories for notebooks recursively."=False)

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 python filename or glob to convert"=None, silent:"Don't print results"=False)

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

Running 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, pause:"Pause time (in secs) between notebooks to avoid race conditions"=0.5)

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

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, pause:"Pause time (in secs) between notebooks to avoid race conditions"=0.5)

Build the documentation by converting notebooks matching 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, replace:"Write replacement notebook back to path_bn"=True)

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 notebooks 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 merging"=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 successful.

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

extract_tgz[source]

extract_tgz(url, dest='.')

nbdev_new[source]

nbdev_new()

Create a new nbdev project from the current git repo

nbdev_new is a command line tool that creates a new nbdev project from the current directory, which must be a cloned git repo.

After you run nbdev_new, please check the contents of settings.ini look good, and then run nbdev_build_lib.