https://github.com/outerbounds/nbdoc
Generate beautiful, testable documentation with Jupyter Notebooks
https://github.com/outerbounds/nbdoc
Last synced: about 1 year ago
JSON representation
Generate beautiful, testable documentation with Jupyter Notebooks
- Host: GitHub
- URL: https://github.com/outerbounds/nbdoc
- Owner: outerbounds
- License: other
- Created: 2022-02-15T04:07:38.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-07-25T16:48:15.000Z (almost 4 years ago)
- Last Synced: 2025-03-23T18:54:14.050Z (about 1 year ago)
- Language: Jupyter Notebook
- Homepage: https://outerbounds.github.io/nbdoc/
- Size: 498 KB
- Stars: 21
- Watchers: 3
- Forks: 2
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# nbdoc
> Generate beautiful, testable documentation with Jupyter Notebooks
[](https://github.com/outerbounds/nbdoc/actions/workflows/main.yml) [](https://pypi.org/project/nbdoc/)
[](https://github.com/fastai/nbdev)
## Install
`pip install nbdoc`
## Usage
This library consists of two cli tools as noted below.
### Converting Notebooks To Markdown
```python
! nbdoc_build --help
```
usage: nbdoc_build [-h] [--srcdir SRCDIR] [--force_all FORCE_ALL]
[--n_workers N_WORKERS] [--pause PAUSE]
Build the documentation by converting notebooks in `srcdir` to markdown
optional arguments:
-h, --help show this help message and exit
--srcdir SRCDIR A directory of notebooks to convert to docs
recursively, can also be a filename.
--force_all FORCE_ALL Rebuild even notebooks that havent changed (default:
False)
--n_workers N_WORKERS Number of workers to use
--pause PAUSE Pause time (in secs) between notebooks to avoid race
conditions (default: 0.5)
### Run and Save Notebooks Inplace
```python
! nbdoc_update -h
```
usage: nbdoc_update [-h] [--srcdir SRCDIR] [--flags FLAGS]
[--n_workers N_WORKERS] [--pause PAUSE]
Refresh all notebooks in `srcdir` by running them and saving them in place.
optional arguments:
-h, --help show this help message and exit
--srcdir SRCDIR A directory of notebooks to refresh recursively, can
also be a filename.
--flags FLAGS Space separated list of flags (tst_flags in
settings.ini) to NOT ignore while running notebooks.
Otherwise, those cells are ignored.
--n_workers N_WORKERS Number of workers to use
--pause PAUSE Pause time (in secs) between notebooks to avoid race
conditions (default: 0.5)
### Testing Notebooks
`nbdoc_test` is just an alias of `nbdev_test_nbs` from [nbdev](https://github.com/fastai/nbdev), and is a lightweight way to test notebooks.
```python
! nbdoc_test --help
```
usage: nbdoc_test [-h] [--fname FNAME] [--flags FLAGS] [--n_workers N_WORKERS]
[--verbose VERBOSE] [--timing] [--pause PAUSE]
Test in parallel the notebooks matching `fname`, passing along `flags`
optional arguments:
-h, --help show this help message and exit
--fname FNAME A notebook name or glob to convert
--flags FLAGS Space separated list of flags
--n_workers N_WORKERS Number of workers to use
--verbose VERBOSE Print errors along the way (default: True)
--timing Timing each notebook to see the ones are slow (default:
False)
--pause PAUSE Pause time (in secs) between notebooks to avoid race
conditions (default: 0.5)
## Automatically Attach Links To APIs in Backticks
```python
! nbdoc_linkify --help
```
usage: nbdoc_linkify [-h] [--local] [--md_path MD_PATH]
Convert names in `backticks` in markdown files that have been documented with
nbdoc.showdoc.ShowDoc to appropriate links.
optional arguments:
-h, --help show this help message and exit
--local Whether or not to build an index based on local documents
(default: True)
--md_path MD_PATH Root path to search recursively containing markdown files
to linkify
## Documentation
Documentation [can be found here](https://outerbounds.github.io/nbdoc/).
## References
nbdoc is built with [nbdev](https://github.com/fastai/nbdev). Furthermore, much of the code in this project is re-purposed from nbdev directly.