Fixes missing and broken links in inheritance diagrams

[ayshih]

Subject: Fixes missing and broken links in inheritance diagrams

Feature or Bugfix

• Bugfix

Purpose

There are multiple bugs that result in missing or broken links in inheritance diagrams. The missing links are due to bugs that break the correct association of external classes with URLs. The broken links are specific to SVG output where the relative paths are not correctly re-pathed. This PR has been rewritten given #11078.

Detail

• Missing links
  • For intersphinx references where a class is found in an external inventory, reftitle does not contain the name of the class – instead, it is "(in <project> <version)" – so the actual name of the class must be separately constructed to build the class<->URL mapping (see inheritance_diagram should support linking via intersphinx #865)
• Broken links
  • Fixed a relative-path bug in ext.inheritance_diagram given the modifications to ext.graphviz in Fix relative references in SVGs generated by sphinx.ext.graphviz #11078

Relates

• Closes inheritance_diagram should support linking via intersphinx #865
• Closes Broken links in inheritance diagrams #3176
• Closes inheritance-diagram 404 links with SVG #10570

[ayshih]

This PR adds more fixes to my already open PR #10576. You can decide whether to review that one first or to simply review this one.

[ayshih]

I've gone ahead and closed #10576 so that there's just a single PR to review (i.e., this one).

Can I please get some feedback on this PR? Thanks!

[AA-Turner]

Can you change the base to 5.x?

A

[ayshih]

Okay, changed and rebased to 5.x

[AA-Turner]

Please avoid pathlib for now, and add tests for the changed behaviour. You also need to add an entry to CHANGES.

A

[ayshih]

Apologies for the noise about the fuzzy matching! When crafting all of the tests, I discovered that the issue with fuzzy matching is actually an interaction with a third-party extension (sphinx-automodapi). I've accordingly ripped out that part of the PR, and the remaining fixes are all for bugs in first-party Sphinx.

[ayshih]

Tests all green, PR ready for re-review, thanks!

[ayshih]

@AA-Turner: I see that you changed the base branch to master, so I've rebased this PR and moved the CHANGES entry to be under 6.0.0 (but it'd be nice if these fixes were backported). Can you please re-review this PR? You may have missed that I added thorough unit tests, so I don't think there's anything else that I need to do. I see that another package has noted the existence of this PR and is also awaiting these long-standing bugs to be fixed.

[ayshih]

@AA-Turner: Sorry to be a bother, but can you please re-review this? All tests are green, including the ones that I added. Thanks!

[AA-Turner]

@ayshih one of the new tests is failing (test_inheritance_diagram_svg_html), please would you have a look?

A

[ayshih]

@AA-Turner: So, it turns out that the recently merged #11078 addresses some of the bugs that are fixed in this PR as well, but from a different angle. This PR is specific to inheritance diagrams and generates the correctly pathed URLs before passing them to the graphviz writer, while #11078 instead modifies the graphviz writer to accept URLs with the "wrong" relative path and rewrites them to have the correct path. Since the graphviz writer has broader uses beyond just inheritance diagrams, I'll update this PR in light of #11078.

I'll note that #11078 actually seems to be slightly buggy, so I'll fix its issues. Also, this PR is not moot because the bug with intersphinx linking still needs to be addressed.

[ayshih]

Okay, this PR has been updated in light of #11078, including fixing links that #11078 inadvertently broke. All tests are green! (I've also tested using a real package (SunPy), and it works as intended.)

[AA-Turner]

Thanks @ayshih!

A

[ayshih]

Thanks!

[pllim]

Hello! Which Sphinx version is this patch expected to be in? 7.1.3? 7.2.0? 8.0?

[AA-Turner]

7.2.

A