# 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/outerbounds/nbdoc/tree/master/",
"name": "nbdoc",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "documentation python jupyter notebook",
"author": "Hamel Husain",
"author_email": "hamel@outerbounds.com",
"download_url": "https://files.pythonhosted.org/packages/11/30/82fbcd41d191d7842d7d641421ec6cb994bbdbb30767af699a2147cd6aad/nbdoc-0.0.82.tar.gz",
"platform": null,
"description": "# nbdoc\n> Generate beautiful, testable documentation with Jupyter Notebooks\n\n\n[](https://github.com/outerbounds/nbdoc/actions/workflows/main.yml) [](https://pypi.org/project/nbdoc/)\n[](https://github.com/fastai/nbdev)\n\n## Install\n\n`pip install nbdoc`\n\n## Usage\n\nThis library consists of two cli tools as noted below.\n\n### Converting Notebooks To Markdown\n\n\n```python\n! nbdoc_build --help\n```\n\n usage: nbdoc_build [-h] [--srcdir SRCDIR] [--force_all FORCE_ALL]\n [--n_workers N_WORKERS] [--pause PAUSE]\n \n Build the documentation by converting notebooks in `srcdir` to markdown\n \n optional arguments:\n -h, --help show this help message and exit\n --srcdir SRCDIR A directory of notebooks to convert to docs\n recursively, can also be a filename.\n --force_all FORCE_ALL Rebuild even notebooks that havent changed (default:\n False)\n --n_workers N_WORKERS Number of workers to use\n --pause PAUSE Pause time (in secs) between notebooks to avoid race\n conditions (default: 0.5)\n\n\n### Run and Save Notebooks Inplace\n\n```python\n! nbdoc_update -h\n```\n\n usage: nbdoc_update [-h] [--srcdir SRCDIR] [--flags FLAGS]\n [--n_workers N_WORKERS] [--pause PAUSE]\n \n Refresh all notebooks in `srcdir` by running them and saving them in place.\n \n optional arguments:\n -h, --help show this help message and exit\n --srcdir SRCDIR A directory of notebooks to refresh recursively, can\n also be a filename.\n --flags FLAGS Space separated list of flags (tst_flags in\n settings.ini) to NOT ignore while running notebooks.\n Otherwise, those cells are ignored.\n --n_workers N_WORKERS Number of workers to use\n --pause PAUSE Pause time (in secs) between notebooks to avoid race\n conditions (default: 0.5)\n\n\n### Testing Notebooks\n\n`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.\n\n```python\n! nbdoc_test --help\n```\n\n usage: nbdoc_test [-h] [--fname FNAME] [--flags FLAGS] [--n_workers N_WORKERS]\n [--verbose VERBOSE] [--timing] [--pause PAUSE]\n \n Test in parallel the notebooks matching `fname`, passing along `flags`\n \n optional arguments:\n -h, --help show this help message and exit\n --fname FNAME A notebook name or glob to convert\n --flags FLAGS Space separated list of flags\n --n_workers N_WORKERS Number of workers to use\n --verbose VERBOSE Print errors along the way (default: True)\n --timing Timing each notebook to see the ones are slow (default:\n False)\n --pause PAUSE Pause time (in secs) between notebooks to avoid race\n conditions (default: 0.5)\n\n\n## Automatically Attach Links To APIs in Backticks\n\n```python\n! nbdoc_linkify --help\n```\n\n usage: nbdoc_linkify [-h] [--local] [--md_path MD_PATH]\n \n Convert names in `backticks` in markdown files that have been documented with\n nbdoc.showdoc.ShowDoc to appropriate links.\n \n optional arguments:\n -h, --help show this help message and exit\n --local Whether or not to build an index based on local documents\n (default: True)\n --md_path MD_PATH Root path to search recursively containing markdown files\n to linkify\n\n\n## Documentation\n\nDocumentation [can be found here](https://outerbounds.github.io/nbdoc/).\n\n## References\n\nnbdoc is built with [nbdev](https://github.com/fastai/nbdev). Furthermore, much of the code in this project is re-purposed from nbdev directly.\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Generate beautiful, testable documentation with Jupyter Notebooks",
"version": "0.0.82",
"project_urls": {
"Homepage": "https://github.com/outerbounds/nbdoc/tree/master/"
},
"split_keywords": [
"documentation",
"python",
"jupyter",
"notebook"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ccb37aa03973805e9d885b9c69021331bdd3ae7d919af6118973768de340c04e",
"md5": "5f7181cf77f1f5f3cf3ae1177bdf64db",
"sha256": "84f57e0c20b389eb748eb2055d55d5698b2f44fdef455943d396112d26103fb9"
},
"downloads": -1,
"filename": "nbdoc-0.0.82-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5f7181cf77f1f5f3cf3ae1177bdf64db",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 23701,
"upload_time": "2022-07-25T16:40:33",
"upload_time_iso_8601": "2022-07-25T16:40:33.228490Z",
"url": "https://files.pythonhosted.org/packages/cc/b3/7aa03973805e9d885b9c69021331bdd3ae7d919af6118973768de340c04e/nbdoc-0.0.82-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "113082fbcd41d191d7842d7d641421ec6cb994bbdbb30767af699a2147cd6aad",
"md5": "a449cc51e5b4fc245b6f978dc69d86e4",
"sha256": "234b785e710025357d66c90be0bf7d620a7a507786380030d749b1c4c5146600"
},
"downloads": -1,
"filename": "nbdoc-0.0.82.tar.gz",
"has_sig": false,
"md5_digest": "a449cc51e5b4fc245b6f978dc69d86e4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26098,
"upload_time": "2022-07-25T16:40:35",
"upload_time_iso_8601": "2022-07-25T16:40:35.172886Z",
"url": "https://files.pythonhosted.org/packages/11/30/82fbcd41d191d7842d7d641421ec6cb994bbdbb30767af699a2147cd6aad/nbdoc-0.0.82.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-07-25 16:40:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "outerbounds",
"github_project": "nbdoc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "nbdoc"
}