How docs.scipy.org and intersphinx affect your doc builds

doc-dev
Tags: #<Tag:0x00007fd88e4908e0>

(Jonathan Sick) #1

For about a day now, docs.scipy.org has been down. This affects DM because our doc system uses intersphinx to help us link to API documentation for third-party packages we use, including scipy and numpy. Since those docs sites aren’t available, Sphinx isn’t able to download their object inventories, and resolve the appropriate links in our docs.

I’m confident the docs.scipy.org problem will resolve itself soon, but here are two temporary mitigations to help you build and preview docs in the meantime.

First, you can try removing these intersphinx dependencies. At the end of your doc project’s conf.py:

del intersphinx_mapping['scipy']
del intersphinx_mapping['numpy']

You can also loosen the strictness of Sphinx builds by removing the -n and -W arguments to the sphinx-build command in your project’s .travis.yml.

Please avoid merging these mitigations to master, though, especially for developer.lsst.io and pipelines.lsst.io. I think we can afford to wait for docs.scipy.org to come back.

Longer term, I think a proper mitigation, that will also increase our build performance, is to deploy a lightweight intersphinx cache microservice. The cache would gather intersphinx inventories and package them for our documentation builds. This would have dual benefits:

  • Remove real-time dependence on third-party doc sites being up from our build toolchain.
  • Rather than hitting multiple websites, the cache microservice can package all object inventories into a single download. This would let us efficiently handle object inventories for hundreds of LSST Sphinx documentation projects.

(Mssgill) #2

Most excellent – inserting those two lines did the trick and got my build speed back up to a few sec, and i’ll only push them for now to the branch, not master, thx @jsick!


(frossie) #3

For interested parties:


(Jonathan Sick) #4

Update

Because of the unexpected persistence of this issue, I’ve now removed the sphinx-build -W flag from the https://pipelines.lsst.io and https://developer.lsst.io projects. If you have open PRs, you can rebase them against master and the usual review+merge workflow can continue. (DM-9815)

It’s clear that an intersphinx caching microservice will be useful for both preventing this issue and improving the intersphinx experience for DM developers (i.e., by making all DM Sphinx projects automatically available with negligible performance cost). I’ve created DM-9819 to cover this work, though it’s currently unscheduled.