Modular nbdev

How to use nbdev’s various tools separately

While nbdev_new gets you started with everything you need to create a delightful Python package, you can also use each of nbdev’s components listed below on their own. You might find this useful if you’re porting a large system over to nbdev, documenting an existing code base, or if you’d like to customize the nbdev workflow for your own project. Note that all of the commands below work without a settings.ini file unless otherwise noted.

Document existing code: show_doc

nbdev allows you to document existing code, even code that is not written in nbdev! nbdev.showdoc.show_doc allows you to render beautiful API documentation in notebooks and on Quarto sites. For example, you can render API documentation for numpy.all like this:

from nbdev.showdoc import show_doc
from numpy import all
show_doc(all)

all

 all (a, axis=None, out=None, keepdims=<no value>, where=<no value>)

Test whether all array elements along a given axis evaluate to True.

Type Default Details
a array_like Input array or object that can be converted to an array.
axis NoneType None Axis or axes along which a logical AND reduction is performed.
The default (axis=None) is to perform a logical AND over all
the dimensions of the input array. axis may be negative, in
which case it counts from the last to the first axis.

.. versionadded:: 1.7.0

If this is a tuple of ints, a reduction is performed on multiple
axes, instead of a single axis or all the axes as before.
out NoneType None Alternate output array in which to place the result.
It must have the same shape as the expected output and its
type is preserved (e.g., if dtype(out) is float, the result
will consist of 0.0’s and 1.0’s). See :ref:ufuncs-output-type for more
details.
keepdims _NoValueType If this is set to True, the axes which are reduced are left
in the result as dimensions with size one. With this option,
the result will broadcast correctly against the input array.

If the default value is passed, then keepdims will not be
passed through to the all method of sub-classes of
ndarray, however any non-default value will be. If the
sub-class’ method does not implement keepdims any
exceptions will be raised.
where _NoValueType Elements to include in checking for all True values.
See ~numpy.ufunc.reduce for details.

.. versionadded:: 1.20.0
Returns ndarray, bool A new boolean or array is returned unless out is specified,
in which case a reference to out is returned.
Note

show_doc automatically parses docstrings that are written in the numpy style. For more information read here.

Testing notebooks: nbdev_test

Testing notebooks can be very useful outside of nbdev, especially if you are documenting an existing code base and want to incorporate tests for your docs. The nbdev_test CLI utility allows you to accomplish this:

You can test an individual notebook with the terminal command:

nbdev_test --path notebook.ipynb

…or a folder of notebooks:

nbdev_test --path tests/

Export code to modules: nb_export

You can export a notebook to a module with the Python function:

nb_export('notebook.ipynb', 'pkg')

…provided the notebook specifies a default_exp directive at the top, and export directives above each cell to be exported. We recommend including this in a code cell at the bottom of your notebook for convenience.

Jupyter-git integration

Jupyter and Git don’t normally play well together, especially for things like merge conflicts. We have outlined all of these problems, and our solutions in this blog post. You can install our merge driver and hooks with the following command:

nbdev_install_hooks

We describe what nbdev_install_hooks does in detail on this page.

You can also directly use any of its underlying commands, for example, to implement your own hooks or extensions:

To configure your own hooks, Check out the pre-commit hooks tutorial.

Python packaging

nbdev.releaseprovides utlities for easy packaging on PyPI, conda, and GitHub. Check out the nbdev.release docs for more information. Note that this functionality requires a settings.ini file.