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#
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