Autodoc regression on sphinx 4

[akhmerov]

Sphinx 4 significantly changes the HTML code generated by the autodoc:

Sphinx 3.5:

<dt id="numpy.linalg.eig">
<code class="sig-prename descclassname"><span class="pre">numpy.linalg.</span></code><code class="sig-name descname"><span class="pre">eig</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#numpy.linalg.eig" title="Permalink to this definition">¶</a></dt>

Sphinx 4.1:

<dt class="sig sig-object py" id="numpy.linalg.eig">
<span class="sig-prename descclassname"><span class="pre">numpy.linalg.</span></span><span class="sig-name descname"><span class="pre">eig</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#numpy.linalg.eig" title="Permalink to this definition">¶</a></dt>

Note how the CSS classes are different and even some codes become spans.

While this doesn't have a profound impact, it breaks theme styling of autodoc captions (originally tracked in #452):

Sphinx 3.5:

Sphinx 4.1:

[bollwyvl]

Turns out the dark code is actually going to be much easier to read, as the pink is one of those things that gets dinged all over by lighthous and pa11y. 🤣 Also, the kerning is more pleasing to my eye between the g and the ( on the new one, as is the consistent font size.

But I digress: it's pretty gross see tags change. Unless we put this under test, comparing pixels between major versions of sphinx, we really can't do much about it, and once shipped, it's hard to put sphinx changes "back in the bottle".

[akhmerov]

Maybe DOM and class changes are worth reporting upstream?

[choldgraf]

@bollwyvl your comment also seems related to #373 I def agree we can revisit the colors!

[choldgraf]

Regarding regressions, one more manual way to do this would be to:

• pin to the latest major sphinx version https://github.com/pydata/pydata-sphinx-theme/blob/master/setup.py
• upon a new major release, our prices for updating includes checking the changelog https://www.sphinx-doc.org/en/master/changes.html and double checking that there's anything there we should follow up on

It's not fool proof but would be a start anyway. Making it a manual upgrade would make us more likely to ask questions like this

[choldgraf]

Another thing we could do is include a "kitchen sink" page in our regression tests, just to make sure base html doesn't change

[lwasser]

hey y'all. i can open a new issue but we've been getting some doc failures with the new version of sphinx. Please see here - it's a jinja issue with the theme and the new version of sphinx. Should i create a new issue for it or does anyone here have any suggestions for what the best fix is? i do have dev requirements pinned and we update via a bot periodically. the newest version of sphinx is still causing things to fail. many thanks and again i'm happy to post this in a new issue but wanted to start here first as this seems to be discussing the newest versions and subsequent issues. many thanks.

[akhmerov]

This issue is specific to autodoc, so perhaps opening a fresh issue would be better. At a glance, the template problem you're facing should be easy to fix in a compatible way.

[lwasser]

thank you @akhmerov !! i did manage to fix it by adjusting dependency versions! this thread was helpful to see as it pinpointed some of the points of change to help me direct the (very easy!) fix. if i run into other issues I will open a new issue.

[akhmerov]

It still seems like a bug in the theme though, or is that not right?

[lwasser]

I suspect the bug was fixed in the theme version 0.6.3 @akhmerov which was the first change that i just made after reading about the issues with sphinx 4.x. After that i've had all successful builds running sphinx 4.x and RTD is building nicely as well. so appreciative of your effort on this theme. it's really nice and user friendly!

[12rambau]

I'm using Sphinx V4.4.0 on my local computer and things seems to be back to normal.
With the addition of a new release policy (#679) can we consider this one solved ?

[choldgraf]

+1 from me!