Metadata-Version: 2.1
Name: nbverbose
Version: 0.0.5
Summary: A helpful extension for nbdev geared towards better documentation
Home-page: https://github.com/muellerzr/nbverbose/tree/master/
Author: Zach Mueller
Author-email: muellerzr@gmail.com
License: Apache Software License 2.0
Keywords: nbdev fastai jupyter
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Provides-Extra: dev
License-File: LICENSE


# 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
):
    "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:


<h4 id="addition" class="doc_header"><code>addition</code><a href="__main__.py#L1" class="source_link" style="float:right">[source]</a></h4>

> <code>addition</code>(**`a`**:`int`, **`b`**:`(<class 'int'>, <class 'float'>)`=*`2`*)

Adds two numbers together

**Parameters:**


 - **`a`** : *`<class 'int'>`*
		The first number to be added


 - **`b`** : *`(<class 'int'>, <class 'float'>)`*, *optional*
		The second number to be added




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
```


<h4 id="addition" class="doc_header"><code>addition</code><a href="__main__.py#L3" class="source_link" style="float:right">[source]</a></h4>

> <code>addition</code>(**`a`**:`int`, **`b`**:`Union`\[`int`, `float`\]=*`2.0`*)

Adds two numbers together

**Parameters:**


 - **`a`** : *`<class 'int'>`*
		The first number to be added


 - **`b`** : *`typing.Union[int, float]`*, *optional*
		The second number to be added




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
```


<h4 id="addition" class="doc_header"><code>addition</code><a href="__main__.py#L1" class="source_link" style="float:right">[source]</a></h4>

> <code>addition</code>(**`a`**:`int`, **`b`**:`Union`\[`int`, `float`\])

Adds two numbers together

**Parameters:**


 - **`a`** : *`<class 'int'>`*
		None


 - **`b`** : *`typing.Union[int, float]`*
		None




```
def addition(a:int,b:Union[int, float]):
    "Adds two numbers together"
    return a+b
```


<h4 id="addition" class="doc_header"><code>addition</code><a href="__main__.py#L1" class="source_link" style="float:right">[source]</a></h4>

> <code>addition</code>(**`a`**:`int`, **`b`**:`Union`\[`int`, `float`\])

Adds two numbers together

**Parameters:**


 - **`a`** : *`<class 'int'>`*
		None


 - **`b`** : *`typing.Union[int, float]`*
		None




{% 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.' %}


