-
-
Notifications
You must be signed in to change notification settings - Fork 7.9k
Doc: Don't use Sphinx 1.8 #12183
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
Doc: Don't use Sphinx 1.8 #12183
Conversation
I'm slowly working on (2), there's a few mathtext-related PRs. |
This means I need to re-generate and re-publish the docs tonight? |
…183-on-v3.0.x Backport PR #12183 on branch v3.0.x (Doc: Don't use Sphinx 1.8)
@tacaswell No pressure. As soon as you have time. I think the search function proves useful especially when a new version is out, so waiting for 2 more weeks might be a bit too long. Btw. is there any data available on how often which site is used? I mean, maybe there are only 9 people other then me actually using the search? 😆 In the long run, how realistic is it to generate the docs automiatically from the respective vx.y.z-doc branch every couple of days, similar to the devdocs? |
Yes, we have google analytics on the site, looks like ~50k hits to search a month... |
manually backported to v3.0.0-doc as ea13253 |
I just pushed the updated docs, should be live in the next 10-15 minutes. |
@tacaswell It doesn't look like search is working in the updated docs at matplotlib.org even though it says to have been built with sphinx 1.7.9.
I noticed that there are also other differences between the docs on the website and the ones created via circle-ci, e.g. the version number seems to be different, but also the "note" box in the examples that was removed in #11428 is still there on matplotlib.org (cf. ci-build vs. web). When I build the docs locally they are in line with the ci-builds. Any idea on a possible difference? Now, sphinx released version 1.8.1 yesterday without fixing the search. So effectively the Concerning search, the fix is not done in sphinx itself as it stands, but one has to modify |
Have you tried refeshing your browser? I had the problem that even with 1.7.9 it used a cached erroneous javascript or something. 😞 on sphinx 1.8.1. So we should |
@timhoffm Try now? I just cleared the cloudflare cache as well. |
@tacaswell Thanks. It works now, though I'm not sure if I had the problem on this machine. |
Wow... so there are remains from the past in my browser, and they are hidden deep. |
Here is the fix for the search: #12216 |
I think I know how to fix the red mathtext symbols (you "just" need to patch the suitable docutils dicts and/or send a patch to docutils) but it's not going to be a priority for me, pinning to 1.7.9 in the meantime is fine. |
Math issue is now tracked in #12532. |
PR Summary
The use of sphinx 1.8 has two downsides
The search on the webpage is broken. See this link or just go to the matplotlib.org and type somthing in the "Quicksearch". To see how it should be, see the 2.2.3 version.
The Writing mathematical expressions tutorial aquires all kinds of red symbols which dont belong there.
While (2) can potentially be fixed from the matplotlib side, (1) cannot. I would hence propose to not use sphinx 1.8 until those are fixed.
PR Checklist