CI: Fail readthedocs build on warning

[michaeldiamant]

Problem

The v1.13.0 build generated incomplete docs, but the build completed successfully.

• Build: https://readthedocs.org/projects/py-algorand-sdk/builds/16823287/
• Docs (note lack of API docs): https://py-algorand-sdk.readthedocs.io/en/v1.13.0/algosdk/auction.html

Due to the lack of build failure, several days passed before we realized the issue. Readthedocs supports failure on warning: https://docs.readthedocs.io/en/stable/config-file/v2.html#sphinx-fail-on-warning.

Since v1.13.0 build included warnings that highlighted the source problem, enabling failure on warning would have provided a Slack notification. See https://github.com/algorand/py-algorand-sdk/pull/332 for warning example + fix.

The story's request is to address existing warnings + fail readthedocs builds on warning.

Solution

Probably out of scope: Catch warnings during PR review rather than in the repo main branch.

• As of writing, readthedocs polls the repo to build (main branch + tags), rather than building the docs are part of the repo's build.
• To catch warnings before merging a PR, I suspect the build model needs to be revisited. I'd consider the effort, but I don't feel it's necessary for us to incrementally realize value.

Dependencies

Urgency

Broken docs hamper community confidence.