Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/muellerzr/nbagile
Making nbdev compatible for agile frameworks and developments
https://github.com/muellerzr/nbagile
Last synced: 2 months ago
JSON representation
Making nbdev compatible for agile frameworks and developments
- Host: GitHub
- URL: https://github.com/muellerzr/nbagile
- Owner: muellerzr
- License: apache-2.0
- Created: 2021-09-13T23:40:57.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2022-03-22T15:22:02.000Z (almost 3 years ago)
- Last Synced: 2024-10-12T15:57:40.670Z (3 months ago)
- Language: Jupyter Notebook
- Homepage:
- Size: 188 KB
- Stars: 29
- Watchers: 4
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-fastai - nbagile - making nbdev compatible for agile frameworks and developments (Other links<a name="other"></a> / Other libraries)
README
# nbagile
> Making `nbdev` more Agile-Friendly
## Install
`pip install nbagile`
## Goals:
- [x] 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](https://muellerzr.github.io/nbverbose)
### Exporting code from `docments` to NumPy
[docments](https://fastcore.fast.ai/docments) is a very efficient way of documenting the parameters for your code, and is akin to how javscript is documented. We utilize comment-blocks and typing to describe how parameters are utilized. For example, we have the following:
```python
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](https://nbdev.fast.ai) 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:
```python
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