Debugging

Readthedocs

We build our docs using readthedocs; unfortunately, jupyter-book logs are confusing. The step that usually fails is the one that renders the documentation, you can identify it because it looks like this:

$CONDA_ENVS_PATH/$CONDA_DEFAULT_ENV/bin/python -m sphinx ...

Click on it and you’ll see the logs. The actual errors are difficult to find so you need to scan through the looks and look for stuff that seems out of place (even warnings). For example, in this build, there are two “errors”:

ERROR | Notebook JSON is invalid: Additional properties are not allowed ('id' was unexpected)

and:

/home/docs/checkouts/readthedocs.org/user_builds/ploomber-engine/checkouts/45/doc/howto/pass-objects.md:15: WARNING: Non-consecutive header level increase; 0 to 2 [myst.header]
l

The second one is harder to see because of the long path at the beginning. These logs are confusing because the build is failing because of the warning (not because of the ERROR). So to debug these builds, ensure you find all the errors and warnings first.