Writing collaborative libraries with nbdev
Project description
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 adocs
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 docstringsnbagile_diff_nbs
: A special version ofnbdev_diff_nbs
to support how nbagile worksnbagile_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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.