Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Autodoc regression on sphinx 4 #460

Closed
akhmerov opened this issue Aug 28, 2021 · 12 comments
Closed

Autodoc regression on sphinx 4 #460

akhmerov opened this issue Aug 28, 2021 · 12 comments

Comments

@akhmerov
Copy link
Contributor

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:

image

Sphinx 4.1:

image

@choldgraf choldgraf changed the title Regression on sphinx 4 Autodoc regression on sphinx 4 Aug 28, 2021
@bollwyvl
Copy link
Collaborator

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
Copy link
Contributor Author

Maybe DOM and class changes are worth reporting upstream?

@choldgraf
Copy link
Collaborator

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

@choldgraf
Copy link
Collaborator

choldgraf commented Aug 29, 2021

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

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
Copy link
Collaborator

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
Copy link
Contributor

lwasser commented Sep 14, 2021

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
Copy link
Contributor Author

akhmerov commented Sep 14, 2021

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
Copy link
Contributor

lwasser commented Sep 14, 2021

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
Copy link
Contributor Author

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

@lwasser
Copy link
Contributor

lwasser commented Sep 14, 2021

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
Copy link
Collaborator

12rambau commented Jun 4, 2022

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
Copy link
Collaborator

+1 from me!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

5 participants