[Doc]: Broken intersphinx objects inventory

[douglas-raillard-arm]

Documentation Link

https://matplotlib.org/objects.inv

Problem

The Sphinx inventory used for intersphinx available at https://matplotlib.org/objects.inv is somewhat empty. Inspecting it with sphobjinv convert plain objects.inv gives:

# Sphinx inventory version 2
# Project: Matplotlib landing page
# Version: 
# The remainder of this file is compressed using zlib.
404 std:doc -1 404.html Page Not Found
genindex std:label -1 genindex.html Index
index std:doc -1 index.html Matplotlib
modindex std:label -1 py-modindex.html Module Index
py-modindex std:label -1 py-modindex.html Python Module Index
search std:label -1 search.html Search Page

Suggested improvement

The inventory should contain links for every class so that intersphinx works.

[douglas-raillard-arm]

Looking at the JSON output of sphobjinv, it looks like sphinx is having trouble generating any xref that comes from the docstrings somewhat:

   "0" : {
      "dispname" : "Page Not Found",
      "domain" : "std",
      "name" : "404",
      "priority" : "-1",
      "role" : "doc",
      "uri" : "404.html"
   },

The only references it gets are ones that probably come from .rst sources.
The json should have loads of entries like this one:

   "1060" : {
      "dispname" : "-",
      "domain" : "py",
      "name" : "lisa.energy_model.ActiveState",
      "priority" : "1",
      "role" : "class",
      "uri" : "energy_analysis.html#$"
   },

[greglucas]

My guess is this is because the base site is a separate sphinx-built landing page and has its own inventory. You likely want to look at the inventory from "/stable", so the intersphinx mapping would look something like this:

'matplotlib': ('https://matplotlib.org/stable/', None)

[timhoffm]

Did https://matplotlib.org/ work before? If so, we should make that work again; probably by replacing the top-level objects.inv by a link.

[douglas-raillard-arm]

It used to work, seems to have broken fairly recently (a month or maybe less). Is there another URL that is supposed to be used for intersphinx ?

EDIT: it looks like some people are using https://matplotlib.org/stable/objects.inv, which does provide a working inventory

[tacaswell]

This is a fallout from:

1. the move of hosting our main docs to 'matplotlib.org/stable' from 'matplotlib.org/' (which solves the "chimera" problem and lets us have a brochure site independent of the built docs)
2. the change in how we host the docs (from ghpages fronted by CloudFlare -> DigitalOcean fronted by CloudFlare) which overlays the full brochure site over the github.matplotlib.org repo (which has a lot of re-directs in it) so that the top-level inventory is now the one from the brochure site.

The best path forward is to use https://matplotlib.org/stable/objects.inv (or the version specific urls e.g. https://matplotlib.org/3.5.0/objects.inv ). I'm inclined to not put it back at top-level permanently. I'm not sure how to do this with any sort of notification or brown-out period so it may be best to just pull the bandaid off.

We definitely need to document this someplace, but I am not sure exactly where.

[tacaswell]

https://github.com/search?o=desc&q=https%3A%2F%2Ffanyv88.com%3A443%2Fhttps%2Fmatplotlib.org%2Fobjects.inv&s=indexed&type=Code suggests there are only 39 instances of this on github which seems.....low?

[douglas-raillard-arm]

I'm inclined to not put it back at top-level permanently

If that's the route taken, I would suggest actually removing the file if possible rather than leaving an almost empty one, at least it will make the error clear and not leave people to wonder if e.g. matplotlib.axes.Axes should be referenced as matplotlib.axes._axes.Axes or similar issues.

[tacaswell]

@douglas-raillard-arm That is a good point. Thinking about this, making that not happen is easy and that should implicitly restore the re-direct and it is more work to rebreak it....

[QuLogic]

Removing the file from the brochure site stopped the shadowing from the matplotlib.github.com site, so it should be back and working again.