Skip to content

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

Merged

Conversation

ImportanceOfBeingErnest
Copy link
Member

PR Summary

The use of sphinx 1.8 has two downsides

  1. 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.

  2. The Writing mathematical expressions tutorial aquires all kinds of red symbols which dont belong there.

image or image

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

  • Has Pytest style unit tests
  • Code is Flake 8 compliant
  • New features are documented, with examples if plot related
  • Documentation is sphinx and numpydoc compliant
  • Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
  • Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

@anntzer
Copy link
Contributor

anntzer commented Sep 20, 2018

I'm slowly working on (2), there's a few mathtext-related PRs.
(1) is known sphinx-doc/sphinx#5460 and milestoned for sphinx 1.8.1, I agree with blacklisting 1.8.0.

@timhoffm timhoffm merged commit f3b97dd into matplotlib:master Sep 20, 2018
meeseeksmachine pushed a commit to meeseeksmachine/matplotlib that referenced this pull request Sep 20, 2018
@tacaswell
Copy link
Member

This means I need to re-generate and re-publish the docs tonight?

tacaswell added a commit that referenced this pull request Sep 20, 2018
…183-on-v3.0.x

Backport PR #12183 on branch v3.0.x (Doc: Don't use Sphinx 1.8)
@ImportanceOfBeingErnest
Copy link
Member Author

ImportanceOfBeingErnest commented Sep 20, 2018

@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?

@tacaswell
Copy link
Member

Yes, we have google analytics on the site, looks like ~50k hits to search a month...

tacaswell pushed a commit that referenced this pull request Sep 21, 2018
@tacaswell
Copy link
Member

manually backported to v3.0.0-doc as ea13253

@tacaswell
Copy link
Member

I just pushed the updated docs, should be live in the next 10-15 minutes.

@ImportanceOfBeingErnest ImportanceOfBeingErnest deleted the doc_dont_use_sphinx18 branch September 22, 2018 00:42
@ImportanceOfBeingErnest
Copy link
Member Author

@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 sphinx!=1.8.0 introduced here is already useless. New ci-builds will use sphinx 1.8.1, again introducing the non-working search and red symbols for mathtext.

Concerning search, the fix is not done in sphinx itself as it stands, but one has to modify layout.html to include some additional javascript. I will try to make a PR with that shortly.

@timhoffm
Copy link
Member

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 sphinx<1.8.0 for the time being.

@tacaswell
Copy link
Member

@timhoffm Try now? I just cleared the cloudflare cache as well.

@timhoffm
Copy link
Member

@tacaswell Thanks. It works now, though I'm not sure if I had the problem on this machine.

@ImportanceOfBeingErnest
Copy link
Member Author

Wow... so there are remains from the past in my browser, and they are hidden deep.
It's rather disturbing to find out that my browser executes some javascript from a site I visited yesterday...
Completely clearing the browser cache did the trick though.

@ImportanceOfBeingErnest
Copy link
Member Author

Here is the fix for the search: #12216
I don't know how far the activities on fixing the red mathtext symbols have moved and whether it would hence make sense to pin sphinx to <=1.7.9 or not.

@anntzer
Copy link
Contributor

anntzer commented Sep 22, 2018

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.

@timhoffm
Copy link
Member

Math issue is now tracked in #12532.

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

Successfully merging this pull request may close these issues.

4 participants