Notes on jupyter-book

We use jupyter-book for our documentation (except for the ploomber package), here are a few things to be aware of.

_config.yaml

Default values we use:

sphinx:
  config:
    # print traceback, otherwise it'll store
    # it in a file and it won't be visible from
    # readthedocs console
    execution_show_tb: True

Notebook caching

Caching notebooks is convenient for rapid local builds but it’s buggy (it relies on the jupyter-cache pacakge). We encountered a problem where one notebook would always crash with a cryptic error, changing to execute_notebook: auto fixed it, but this implies losing the caching feature.

execute:
    execute_notebook: cache

Dynamic Binder links

We build our documentation on each PR. To build dynamic Binder links that allow us to quickly test the code in the PR, we need to make a few changes to the default jupyter-book configuraton:

1. Generate config.py from _config.yml with jupyter-book config sphinx path/to/doc

2. Change .readthedocs.yml: we no longer need the jupyter-book config sphinx in the pre-build step

3. Update the docs environment (usually doc/environment.yml, but check .readthedocs.yml): add pkgmt>=0.1.7 under the pip section

4. Modify conf.py you can use sklearn-evaluation’s as reference.