nbdoc 0.0.21

Generate beautiful, testable documentation with Jupyter Notebooks

nbdoc

Generate beautiful, testable documentation with Jupyter Notebooks

Install

Note: nbdoc requires python 3.9 or higher

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 matching `fname` to html

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)

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)

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.