An add-on to nbdev that allows for explicit parameter documentation
pip install nbverbose
This library acts as an in-place replacement for nbdev's show_doc functionality, and extends it to allow for documentation of the inputs. It is also built on top of the docments functionality inside of fastcore: docs
Everything else with nbdev runs fine, and you should use normal nbdev conventions, however instead of doing from nbdev.showdoc import *, you should do from nbverbose.showdoc import *.
An example of what will happen can be found below
First we import the library:
from nbverbose.showdoc import *
Next we'll write a very basic function, that has a new way to document the inputs.
Rather than needing to have a very long doc string, your code can follow this declaration format. Spacing etc is not needed, just each parameter must be on a new line:
def addition(
a:int, # The first number to be added
b:(int, float)=2, # The second number to be added
)-> (int,float): #Either int or float will be returned depending on `b`
"Adds two numbers together"
return a+b
As you can see, the documentation format is name followed by the type (as normal), but in a single-line comment afterwards you put a quick affiliated documentation string for it.
When you call the show_doc or doc functions, wrapping around addition, it will look something like so:
addition[source]
addition(a:int,b:(<class 'int'>, <class 'float'>)=2)
Adds two numbers together
| Parameters: | Type | Default | Details |
|---|---|---|---|
a |
<class 'int'> |
No Default | The first number to be added |
b |
(<class 'int'>, <class 'float'>) |
2 |
The second number to be added |
| Return Type | Details |
|---|---|
(<class 'int'>, <class 'float'>) |
Either int or float will be returned depending on b |
We can see that our types are properly formatted. This even works in cases such as Union or List:
from typing import Union
def addition(
a:int, # The first number to be added
b:Union[int, float]=2., # The second number to be added
):
"Adds two numbers together"
return a+b
addition[source]
addition(a:int,b:Union[int,float]=2.0)
Adds two numbers together
| Parameters: | Type | Default | Details |
|---|---|---|---|
a |
<class 'int'> |
No Default | The first number to be added |
b |
typing.Union[int, float] |
2.0 |
The second number to be added |
| Return Type | Details |
|---|
|
Any functions that normally don't follow this format can still work as well:
def addition(
a:int,
b:Union[int, float],
):
"Adds two numbers together"
return a+b
addition[source]
addition(a:int,b:Union[int,float])
Adds two numbers together
| Parameters: | Type | Default | Details |
|---|---|---|---|
a |
<class 'int'> |
No Default | |
b |
typing.Union[int, float] |
No Default |
| Return Type | Details |
|---|
|
def addition(a:int,b:Union[int, float]):
"Adds two numbers together"
return a+b
addition[source]
addition(a:int,b:Union[int,float])
Adds two numbers together
| Parameters: | Type | Default | Details |
|---|---|---|---|
a |
<class 'int'> |
No Default | |
b |
typing.Union[int, float] |
No Default |
| Return Type | Details |
|---|
|
{% include note.html content='The [source] button on these examples will not point to something existing. This is due to the fact that addition is not part of our library. This will work fine for anything done with your nbdev-built library.' %}