Skip to content

Doc: Don't use Sphinx 1.8#12183

Merged
timhoffm merged 1 commit into
matplotlib:masterfrom
ImportanceOfBeingErnest:doc_dont_use_sphinx18
Sep 20, 2018
Merged

Doc: Don't use Sphinx 1.8#12183
timhoffm merged 1 commit into
matplotlib:masterfrom
ImportanceOfBeingErnest:doc_dont_use_sphinx18

Conversation

@ImportanceOfBeingErnest

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

anntzer commented Sep 20, 2018

Copy link
Copy Markdown
Contributor

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
Copy Markdown
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

ImportanceOfBeingErnest commented Sep 20, 2018

Copy link
Copy Markdown
Member Author

@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
Copy Markdown
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
Copy Markdown
Member

manually backported to v3.0.0-doc as ea13253

@tacaswell

Copy link
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
Member

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

@timhoffm

Copy link
Copy Markdown
Member

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

@ImportanceOfBeingErnest

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

anntzer commented Sep 22, 2018

Copy link
Copy Markdown
Contributor

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
Copy Markdown
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