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#$"
   },

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)

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.

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

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.

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

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.

@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....

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

Two cents: Choosing to delete the file at https://matplotlib.org/objects.inv was absolutely the right way to go, versus adding a link/redirect from /objects.inv to /stable/objects.inv

A redirect would at minimum lead to a lot of link redirects for incoming traffic, and possibly have the potential to break the site in funny ways. Far better for a request to /objects.inv to just 404.

The way intersphinx works when forming the URL to insert into built docs, it takes the first item in the intersphinx_mapping tuple value as the base URL for the docset, and then appends the relative URI for the object being cross-referenced to it, as found for that object in its objects.inv entry.

So, if someone sets up their intersphinx_mapping with an entry for "matplotlib": ("https://matplotlib.org/", None), and the inventory is retrieved from .../stable/objects.inv after a redirect, the URLs produced by intersphinx will not include the internal /stable/... they'll be https://matplotlib.org/api/path/to/page.html#anchor.

Currently, it looks like the matplotlib.org site is set up to redirect most things(?) from / to /stable. Thus, an objects.inv redirect would work for now, though introducing a whole bunch of incoming requests needing that redirect. But, it would increase maintenance burden for the site, and also make it brittle against a possible future need for a more complex redirect strategy.

Thank you for the context @bskinn !

We are doing the "redirect" with a symlink so there is no chance sphinx will know. If we were to properly use a 301 will sphinx correctly deal with that?

https://github.com/sphinx-doc/sphinx/blob/fc428ad324ef38402f1e93b38c61cd6348980ed2/sphinx/ext/intersphinx.py#L158-L194 suggests that sphinx can detect if it got moved, but I think we would have to move to re-directs. Now that we are self-hosting I think this is a thing we can actually do @QuLogic ?

We are doing the "redirect" with a symlink so there is no chance sphinx will know. If we were to properly use a 301 will sphinx correctly deal with that?

Looking at _read_from_url(), I would think that as long as requests can tolerate your configuration, Sphinx should be fine with it, too.

I guess, to be clear, @tacaswell, in these last two posts, are you talking about a redirect just for objects.inv? Or redirects for all of the pages based on /, to the real pages based on /stable/?