1413975 - Investigate recent intermittent Read the Docs build failures

Status: RESOLVED FIXED

(Tree Management :: Treeherder, enhancement, P1)

Description

[Ed Morley [:emorley]]

We've had quite a few failures recently:
https://readthedocs.org/projects/treeherder/builds/

Comment 1

[Ed Morley [:emorley]]

So four of the failures turn out to be an intermittent issue other people saw last week too:
https://github.com/rtfd/readthedocs.org/issues/3183

Another one was this:
https://github.com/rtfd/readthedocs.org/issues/2901

And for the most recent, there wasn't an existing issue, so I've filed:
https://github.com/rtfd/readthedocs.org/issues/3219

For the second of the links above, it appears to be caused when two docs builds are triggered within short succession of each other - presumably due to them overlapping. One way to avoid this would be to try and speed up the build slightly.

The current breakdown is:
* creating virtualenv (RTD built-in step): 2s
  -> it seems to be re-creating even if the venv exists
  -> Filed: https://github.com/rtfd/readthedocs.org/issues/3221
* pip install of RTD packages (RTD built-in step): 5s
  -> time is wasted clobbering our existing version of Sphinx
* pip install of our requirements/docs.txt: 2s
  -> time is wasted reinstalling our newer version of Sphinx
* setup.py install (RTD built-in step): <1s
  -> we don't need this step, so I've now disabled it via the RTD project admin settings
* cat docs/conf.py (RTD built-in step): 0s
* sphinx-build of type readthedocs: 5s
* sphinx-build of type json: 2s
  -> not sure if this is used by the search feature or unused?
  -> there isn't a way to turn it off at the moment though
* sphinx-build of type readthedocssinglehtmllocalmedia: 1s
  -> we don't need this, but there isn't a way to turn it off
  -> Filed: https://github.com/rtfd/readthedocs.org/issues/3220

It also appear that we're no longer making use of sphinxcontrib-httpdomain, which was the only reason we needed RTD to use `requirements/docs.txt`. That means we can disable the "use custom requirements file" feature of RTD, avoiding the Sphinx churn issue above.

Comment 2

[Treeherder GitHub Bugbot]

Commits pushed to master at https://github.com/mozilla/treeherder

https://github.com/mozilla/treeherder/commit/644b0d900f4bbc8eaa944389848beca7a9578700
Bug 1413975 - Docs: Disable unused Sphinx extensions

This means less to both install and run at build time, hopefully
speeding up the build and reducing the chance of races/locking issues.

https://github.com/mozilla/treeherder/commit/8b6743456e6ab54a8d1e419253e7a5e6230a0658
Bug 1413975 - Docs: Remove redundant configuration from conf.py

Most of the existing config (generated by `sphinx-quickstart`) was
either commented out, identical to the defaults or else for build
modes we do not use - and only end up making the config hard to read.