nbagile

Making nbdev more Agile-Friendly

Install

pip install nbagile

Goals:

• When exporting source code using docments, attach and format the docstring to Numpy format
• Export tests and throw them into a pytest-compatible file format
• Make documentation run on Sphynx
• Tests are exported to a tests folder, source code to a source code folder, and Markdown/Sphynx documentation to a docs folder
• Individual notebooks can then be recreated from these three items

Current Capabilities

Using the CLI

Replace nbdev_ commands with nbagile_ to use it's capabilities. Currently Supported:

• nbagile_build_lib: Exports code and converts it to black-style + NumPy docstrings
• nbagile_diff_nbs: A special version of nbdev_diff_nbs to support how nbagile works
• nbagile_build_docs: Builds the docs using nbverbose

Exporting code from docments to NumPy

docments is a very efficient way of documenting the parameters for your code, and is akin to how javascript is documented. We utilize comment-blocks and typing to describe how parameters are utilized. For example, we have the following:

def addition(
    a:int, # The first number to add
    b:(int,float), # The second number to add
) -> int: # The sum of a and b
    "Adds a and b"
    return a+b

But this is not the commonly accepted way of documenting our code, and as a whole looks quite ugly.

nbagile supports building your nbdev built libraries to instead automatically convert this code into a more NumPy-styled documentation string and definition, with the added bonus of it mimicing the Black format:

def addition(a,b):
    """Adds a and b
    
    Parameters
    ----------
    a : int
      The first number to add
    b : (int,float)
      The second number to add
      
    Returns
    ----------
    int
      The sum of a and b
    """
    return a+b

This works for functions, classes, as well as functions wrapped around decorators.

Optional __all__ for nbdev

If you are not a fan of nbdev's __all__ format in each file, there is an additional setting you can add to your settings.ini: use_all.

If set to False, you won't get the __all__ being generated in each python file