Sphinx Gallery API pages + deprecating old examples folder

[choldgraf]

Demo here

This is an attempt at getting the API docs to build with sphinx-gallery. Once this works, we'll be able to remove use of the .. plot:: directive and use sphinx-gallery auto-linking instead. I'm also building examples of the docs on my fork which I'll link to below.

I've got API references working for a subset of the API docs. For now I'm leaving in the .. plot:: directive stuff so we can compare.

Pinging @QuLogic @phobson @NelleV @anntzer and @dopplershift as they've been super helpful in the documentation improvements so far!

This PR essentially accomplishes these things:

1. break up the main pyplot page so that it instead exists as a bunch of stubs instead of one mega page.
   Here's an example of how this would look:

   New version
   Old version

2. Auto-links mini-galleries of examples for any of the pyplot functions.
   Here's an example of this

3. Re-links anything pointing to doc/examples to instead link to doc/gallery.

4. Moved any .py files that were embedded in the user documentation into the examples folder.

5. Disables generating the doc/examples folder because this is all now being done by sphinx-gallery.
   This means doc builds will take ~12 minutes the first time, and ~3 minutes if the gallery has already been built (!!).

Future stuff will be to make sure that we have as many mini galleries being linked properly in the API pages.

[anntzer]

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?

[choldgraf]

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 :)

[efiring]

The proposed new pyplot page scheme is a great improvement.

[story645]

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

[choldgraf]

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.

[choldgraf]

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

[story645]

Is this a bug or a ToDo?

[choldgraf]

A bug to be squashed. It's because of the html theme mpl uses.

…

On Sat, Apr 22, 2017, 6:40 PM hannah ***@***.***> wrote: Is this a bug or a ToDo? [image: screen shot 2017-04-22 at 9 39 45 pm] <https://cloud.githubusercontent.com/assets/1300499/25309783/3e309af6-27a4-11e7-93c3-5e37b2eb0c19.png> — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#8525 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABwSHdkmiIe139iw8r-PifbEiGwkcU4sks5ryqwKgaJpZM4NEnCk> .

[choldgraf]

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!)

[QuLogic]

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

[choldgraf]

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.

[story645]

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

[QuLogic]

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

[choldgraf]

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

[choldgraf]

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

[dstansby]

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.

[choldgraf]

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

[choldgraf]

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

[choldgraf]

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.

[QuLogic]

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

[anntzer]

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

[choldgraf]

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

[story645]

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:

[choldgraf]

@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

[dstansby]

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.

[choldgraf]

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

[choldgraf]

(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)