Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/muellerzr/nbverbose
An inplace extension on fastai's nbdev library to support documenting inputs
https://github.com/muellerzr/nbverbose
Last synced: 3 months ago
JSON representation
An inplace extension on fastai's nbdev library to support documenting inputs
- Host: GitHub
- URL: https://github.com/muellerzr/nbverbose
- Owner: muellerzr
- License: apache-2.0
- Created: 2021-08-03T22:40:23.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2022-01-23T20:08:22.000Z (almost 3 years ago)
- Last Synced: 2024-09-29T00:01:43.585Z (3 months ago)
- Language: Jupyter Notebook
- Size: 85 KB
- Stars: 3
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-fastai - nbverbose - An inplace extension on fastai's nbdev library to support documenting inputs (Other links<a name="other"></a> / Other libraries)
README
# Verbose nbdev (nbverbose)
> An add-on to nbdev that allows for explicit parameter documentation
## Install
`pip install nbverbose`
## How to use
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](https://fastcore.fast.ai/docments)
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`**:`(, )`=*`2`*)
Adds two numbers together
|**Parameters:**|Type|Default|Details|
|---|---|---|---|
|**`a`**|``|*No Default*|The first number to be added|
|**`b`**|`(, )`|`2`|The second number to be added|
|**Return Type**|Details|
|-|-|
|`(, )`|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`**|``|*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`**|``|*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`**|``|*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.' %}