Readthedocs#

This is the default configuration we use:

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "mambaforge-4.10"

  jobs:
    # delete pre_build if using conf.py, keep it if using _config.yml
    pre_build:
      - "jupyter-book config sphinx doc/"

    # this will print all dependencies and versions, useful for debugging
    post_create_environment:
      - "conda env export"

conda:
  environment: doc/environment.yml

sphinx:
  builder: html
  fail_on_warning: true

More details below.

fail_on_warning#

At this time of writing, Jupyter Book (0.13.1) only emits warnings (not errors) when a notebook fails. Hence, the only way to make the readthedocs build fail is by setting fail_on_warning.

sphinx:
  builder: html
  fail_on_warning: true

However, this setting makes the doc building process too strict.

Build docs on PRs#

See here.

Debugging failed notebooks#

Readthedocs includes ANSI color codes in the notebook’s traceback, which are unreadable in the readthedocs build. Example:

Cell [0;32mIn[4], line 3[0m
[1;32m      1[0m [38;5;28;01mfrom[39;00m [38;5;21;01msklearn_evaluation[39;00m [38;5;28;01mimport[39;00m plot
[0;32m----> 3[0m cm [38;5;241m=[39m [43mplot[49m[38;5;241;43m.[39;49m[43mInteractiveConfusionMatrix[49m[38;5;241;43m.[39;49m[43mfrom_raw_data[49m[43m([49m
[1;32m      4[0m [43m    [49m[43my_test[49m[38;5;241;43m.[39;49m[43mtolist[49m[43m([49m[43m)[49m[43m,[49m
[1;32m      5[0m [43m

To fix it, use the following script, which will print the logs in your terminal (which can render ANSI color codes):

pip install pyppeteer

# get the script
curl -O https://raw.githubusercontent.com/ploomber/contributing/main/scripts/rtdlogs.py

# run it
python rtdlogs.py https://readthedocs.org/projects/PROJECT/builds/BUILD

More info: ploomber/contributing#77