Somewhat side-tangent (haven't reviewed the full PR): I like the splitting of the huge pyplot page (similarly to how the Axes class doc was split), but I wonder whether it would be possible to use some js trickery to make the docs for each individual function expand below the entry whenever the entry is clicked?

I wonder whether it would be possible to use some js trickery to make the docs for each individual function expand below the entry whenever the entry is clicked?

This would probably be possible though I bet it'd be quite messy. I think first step is to get the stub pages generated / linked in this PR. Basically my goal is to make us no longer rely on the plot directive and get all of the API docs doing auto-linking to examples etc. JS trickery should be a feature for later :)

The proposed new pyplot page scheme is a great improvement.

@1. (+1 on new version) and 2. make me so incredibly happy. I'm tempted to say all the modules w/ 2, but I think practically it depends on what sort of examples are attached to which models.
3. I think it's maybe - depends on how long it takes-worth making a list of orphan methods and seeing if they're redundant/overlapping/still attached to functionality, etc.

A quick thought:

on 3, I'd prefer to just switch over to sphinx-gallery and remove the plot directives, and try to work with the SG team to improve their method finding etc.

Latest push has (nearly) all .. plot:: instances removed. Will get to the rest this weekend!

e.g.:

http://predictablynoisy.com/matplotlib/faq/howto_faq.html

Is this a bug or a ToDo?

ok bugs squashed, broken links unbroken. I think this is a pretty decent-sized bite to take in the current docs so I don't want to change too much else in this PR.

Somebody take a look and LMK what you think.

After this is merged, the old examples folder won't be generated anymore, which means that after the first time sphinx gallery is run, it'll only take 2-3 minutes to build the docs after this (yay!)

This commit from #8346 shows that the doc builds were silently failing before. It looks like they're working correctly here, which is good.

yeah I looked through the doc builds on travis to make sure I didn't see the word "Exception" in there anywhere. I saw your post on the MPL gitter.

Non blocking nitpick, but is there a way to move api above animation in the examples or is it all auto?

Front page has a big yellow "Could not find Snippet to insert at /versions.html" right below Documentation (I assume the link in the top post is to the latest build.)

@story645 that's a good question, I agree that we probably want certain example sections before others. I'll open an issue on the SG repo to see if that's supported.

@QuLogic it's been that way on my computer since I've tried...I assume this is because I don't have any other versions of the docs on my machine? Does that not show up for you when you build them locally?

@story645 looks like this will come eventually but it's not here yet :) sphinx-gallery/sphinx-gallery#37 (comment)

I'm currently building this locally, and will try to review tonight!

A thought that can be dealt with elsewhere:

Is there a way to turn

Executing file /Users/dstansby/matplotlib/examples/mplot3d/contour3d_2.py
/Users/dstansby/matplotlib/examples/mplot3d/contour3d_2.py ran in : 0.15 seconds

into just

Executing file /Users/dstansby/matplotlib/examples/mplot3d/contour3d_2.py

Currently it's very hard to see which examples are throwing warnings.

@dstansby not currently. I believe that one of the MPL devs (maybe @QuLogic or @anntzer ?) recently opened an issue on the SG repo to discuss this. My guess is that the SG devs would be friendly to it but in the "you're free to open a PR to contribute this" sense.

Usually what I do is just wait for all of SG to build and quickly scan back through the output.

@story645 I'm working on re-working the API index page, which would make it much easier to build sphinx-gallery pages for all the modules. I'll show this off in an upcoming push and we can decide if it's worth keeping.

@story645 so after playing around w/ it a bit, I think that it may be a little tricky to auto-build all of the modules. Instead I've modified the most-used API pages (according to google analytics) to use SG in the latest commit. I think that fully converting all the API pages to sphinx gallery is better for a future PR as this one is already changing quite a bunch of stuff, but it should be doable!

also pinging @dstansby to make sure that you see the latest push (not a gigantic change tho). I won't modify this PR any more today so it can give people time to comment.

@dstansby / @choldgraf yep, it's sphinx-gallery/sphinx-gallery#230.

(don't wait for me for this PR, I have a few other things on my plate these days)

Travis is passing again, and I don't think appveyor error is related to this PR (but correct me if I'm wrong).

@dstansby I also wanted to make sure you know that the docs are also being built on my fork of matplotlib and hosted online, here: http://predictablynoisy.com/matplotlib/

The modules that are now built with autosummary (and thus sphinx-galleryified) are:

• pyplot summary
• pyplot
• colors
• axes
• axis
• lines
• markers
• patches

This all makes me so happy 'cause it makes it really easy to figure out what doesn't have examples. 'nother I think it's an html bug:

@story645 fwiw I think that's a bug that was there before this PR, this is from the matplotlib.org page:

http://matplotlib.org/api/api_changes.html

The problem is long words that are larger than the width of the sidebar. Not sure the best way to deal with this tho

I've had a fairly good look through this, and all looks good. It's a pretty big change, so I think using the devdocs as much as possible before 2.1 is released is definitely a good idea to catch anything that falls through the net.

@dstansby I think that's a good point - there is still much to improve in the docs, but I think this will be the last big change for this set of PRs. From here on it can hopefully be spot-checking specific things and/or converting specific folders / examples / etc to sphinx gallery!

(latest push is super tiny, it's just adding the gridspec module to be sphinx-galleryified since there's another example being built for it)