nbdoc

Generate beautiful, testable documentation with Jupyter Notebooks

Install

pip install nbdoc

Usage

This library consists of two cli tools as noted below.

Converting Notebooks To Markdown

! 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

! 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, and is a lightweight way to test notebooks.

! 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

! 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.

References

nbdoc is built with nbdev. Furthermore, much of the code in this project is re-purposed from nbdev directly.

outerbounds/nbdoc