Sphinx class inheritance diagrams not linking classes correctly

[MSeifert04]

Blocked by

• sphinx 7.2, see Fixes missing and broken links in inheritance diagrams sphinx-doc/sphinx#10614 (comment)
• sphinx-automodapi 0.16 with Fix broken inheritance-diagram links due to the smart resolver sphinx-automodapi#172

---

In class inheritance diagrams the links to the classes are broken. For example here.

The problem seems to be that these links don't include the branch, for example:

• Link: http://astropy.readthedocs.io/en/api/astropy.wcs.NoSolutionError.html#astropy.wcs.NoSolutionError does not work
• but http://astropy.readthedocs.io/en/latest/api/astropy.wcs.NoSolutionError.html#astropy.wcs.NoSolutionError (with the latest) does.

Not sure if this is astropy related. If not could you point me in the right direction?

[bsipocz]

This is a duplicate for astropy/photutils#345. One fix was done in sphinx-doc/sphinx#2484, but there are issues with it and I haven't got time yet to get back to it. However it's on my list to do before 1.2.

[larrybradley]

@bsipocz Any update on this?

[bsipocz]

@mirca @dpshelio - I can't remember whether you find any workarounds for this, or just the one I had the PR in sphinx?

[mirca]

@bsipocz We ended up implementing the same solution you thought.

[Cadair]

Crikey have these really been broken for this long, shows you how much attention I pay.

[bsipocz]

@mirca - ouch, I though you've found a patch for https://github.com/astropy/sphinx-automodapi that would make it work again.

[amcnicho]

I noticed another instance of this issue (docs/coordinates/index.rst is affected) and also realized that the links in the generated inheritance diagrams are only missing the branch name. I checked the build page and it seems that sphinx_automodapi is apparently run without graphviz explicitly installed:

python3.6 -mvirtualenv --system-site-packages /home/docs/checkouts/readthedocs.org/user_builds/astropy/envs/latest 
/home/docs/checkouts/readthedocs.org/user_builds/astropy/envs/latest/bin/python -m pip install --upgrade --cache-dir /home/docs/checkouts/readthedocs.org/user_builds/astropy/.cache/pip pip 
/home/docs/checkouts/readthedocs.org/user_builds/astropy/envs/latest/bin/python -m pip install --upgrade --cache-dir /home/docs/checkouts/readthedocs.org/user_builds/astropy/.cache/pip -I Pygments==2.3.1 setuptools==41.0.1 docutils==0.14 mock==1.0.1 pillow==5.4.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.8.1 recommonmark==0.5.0 sphinx<2 sphinx-rtd-theme<0.5 readthedocs-sphinx-ext<1.1

This is contrary to instructions in the documentation, which state graphviz as a dependency for inheritance diagrams. Could a fix for this issue be as straightforward as updating the CI system to ensure that library is installed before documentation builds?

Update: I found that the graphviz system library is installed by the CI configuration but I still wonder whether the pip wheel should be installed (by adding it to the docs venv package list used by tox). The python version of the library does seem necessary based on my cursory examination of the relevant class in sphinx_automodapi.

[embray]

Just rediscovered this issue when using Astropy as a nice demonstration of class inheritance diagrams. I can't believe this has been broken for 6 years 🤯

I'll have a look into it.

[ayshih]

I've put up a PR (astropy/sphinx-automodapi#152) that finally fixes this bug

[ayshih]

Upon further testing, I discovered that the true bug is in Sphinx after all, and has nothing to do with sphinx_automodapi. See sphinx-doc/sphinx#10576

[ayshih]

I'll point out that even after Sphinx accepts the bugfix for current releases, the Astropy docs are currently being built against a rather old version of Sphinx. You'll almost certainly need to undo the sphinx<4 pin (see #11725) to get working inheritance diagrams.

[pllim]

Yeah, to unpin Sphinx, we also need to figure out astropy/sphinx-automodapi#150 from @saimn .

[pllim]

Update: We have unpinned Sphinx in #14140

[ayshih]

The bug fixes have been merged upstream (sphinx-doc/sphinx#10614 and astropy/sphinx-automodapi#172), so will presumably show up in respective new releases, but there will potentially be an incompatibility between our theme and the next release of Sphinx (see pydata/pydata-sphinx-theme#1404).

[ayshih]

It took over seven years, but this issue can finally be closed! Proof: https://docs.astropy.org/en/latest/time/ref_api.html#class-inheritance-diagram (which also correctly links to the Python docs if you click on the tzinfo box)

[pllim]

Thank you, @ayshih !!!