Summary

When doc builds fail, most of the time it's due to ReST formatting or referencing issues.

Most issues have a form similar to

/home/circleci/project/doc/api/next_api_changes/behavior/22135-JSS3.rst:3: WARNING: py:obj reference target not found: Figure._localaxes

My standard way to find out the error is:

• Open CircleCI
• Download the build log
• Search for "WARNING"

This is cumbersome and not very discoverable for new contributors.

Proposed fix

It would be great to have a bot post these warnings if CicleCI fails. I assume that would cover 95% of doc build failures and point contributors (new and experienced) to the problem so that they can solve it faster.