Tie intersphinx inventory locations to versions being installed

[bsipocz]

It may be rather useful is we would tie the location of the intersphinx inventories to the version of the packages we build the docs with. E.g. currently the docs build for astropy core is failing due to some unresolvable links, but the docs otherwise builds perfectly: astropy/astropy#6695

The failures are due to some issues with the intersphinx of the brand new 2.1 of matplotlib. While for the docs we still use the 2.0.2 version. I foresee that similar issues could emerge later, too so it would be nice to link to actually resolve the links to the version we build the docs with.

[MSeifert04]

Not every package has automatic documentation uploads, for example it wouldn't work for NumPy. I don't know when they upload the docs but some versions don't get new documentation.

For example:

• https://docs.scipy.org/doc/numpy-1.13.0/reference/generated/numpy.sum.html - works
• https://docs.scipy.org/doc/numpy-1.13.1/reference/generated/numpy.sum.html - doesn't

But:

• https://docs.scipy.org/doc/numpy-1.10.0/reference/generated/numpy.sum.html - works
• https://docs.scipy.org/doc/numpy-1.10.4/reference/generated/numpy.sum.html - works

[MSeifert04]

Aside from that: I don't know if it's actually helpful, astropy is one of the few projects that actually builds the docs as part of the tests and errors in case of intersphinx failures - so it's likely no one found out about the problem until mpl 2.1 is available on conda - and when that happens we would get the failures anyway if we don't limit the mpl version.

[bsipocz]

Aside from that: I don't know if it's actually helpful, astropy is one of the few projects that actually builds the docs as part of the tests and errors in case of intersphinx failures - so it's likely no one found out about the problem until mpl 2.1 is available on conda - and when that happens we would get the failures anyway if we don't limit the mpl version.

Yes, but limiting the version would mean that we can wait for the upstream fix.

Also, I mean to follow the main versions not the bugfixes as the api doesn't expected to change for those. E.g. 1.13.0 and 1.13.1 would have the same inventory, as actually looking at the ones for 1.10.0 and 1.10.4, they are exactly the same.

[MSeifert04]

We could also use the latest stable object-inv in the intersphinx mapping manually: https://matplotlib.org/2.0.2/objects.inv (temporarily)

[MSeifert04]

Yes, but limiting the version would mean that we can wait for the upstream fix.

You're right. I was just thinking that if we limit versions we could as well manually limit the intersphinx target. That's probably easier to do manually and revert than to build an infrastructure to fetch the intersphinx of the currently installed version (which may be problematic in case one uses older versions where the intersphinx had a different mapping - not in case of CI but for developers building the docs locally).

[bsipocz]

I wouldn't say it's easier, as the intersphinx mapping is provided by the helpers, and thus we either need to do the limit by hand in every affected package, or do this feature once and it will work once a package decides to limit the version they're building their docs. I think the proposed way is more consistent, and implementation shouldn't be too difficult either.

[nstarman]

@bsipocz, @MSeifert04
This would be very useful for #40. Is there any consensus on how to implement this?