Repository navigation
[Doc]: Broken intersphinx objects inventory #22601
Description
Activity
- added a commit that references this issue
on Mar 4, 2022 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#$" },- added a commit that references this issue
on Mar 4, 2022 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.invby 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:
- 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)
- 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.Axesshould be referenced asmatplotlib.axes._axes.Axesor 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.comsite, so it should be back and working again.Two cents: Choosing to delete the file at
https://matplotlib.org/objects.invwas absolutely the right way to go, versus adding a link/redirect from/objects.invto/stable/objects.invA 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.invto just 404.
The way
intersphinxworks when forming the URL to insert into built docs, it takes the first item in theintersphinx_mappingtuple 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 itsobjects.inventry.So, if someone sets up their
intersphinx_mappingwith an entry for"matplotlib": ("https://matplotlib.org/", None), and the inventory is retrieved from.../stable/objects.invafter a redirect, the URLs produced byintersphinxwill not include the internal/stable/... they'll behttps://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, anobjects.invredirect 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.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 asrequestscan 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/?
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.invgives:Suggested improvement
The inventory should contain links for every class so that intersphinx works.