Looks good to me. (And the green button is there!). I'm fine with merging this now, but would like @pelson's view about whether it will be easiest to do this before or after #1918.

If it's easier to merge #1918 first, I don't mind redoing the rebase.

I've just checked out a fresh clone of this and was unable to build the docs:

reading sources... [  0%] api/axes_api                                                                                                                
Exception occurred:
  File "<path to global matplotlib install>/matplotlib/sphinxext/plot_directive.py", line 670, in run
    with open(source_file_name, 'r') as fd:
IOError: [Errno 2] No such file or directory: u'<path to local matplotlib install>/doc/mpl_examples/pylab_examples/errorbar_demo.py'
The full traceback has been saved in /var/tmp/sphinx-err-o5We0U.log, if you want to report the issue to the developers.

Any ideas? @NelleV have you ever seen this?

Any ideas? @NelleV have you ever seen this?

Looks like my paths are a little odd. I think I know the problem, now time to find a solution 😄...

@pelson If seen this before: I think doing a make clean solves the problem. You also need to make sure you've got the proper version of matplotlib installed (ie you need to check you are building the documentation at time T of the matplotlib version at time T, and not at time T - n) .

I think doing a make clean solves the problem

Hmmm, yes, normally I'd agree, but because the clean wasn't working I took a whole new clone of this branch and it still failed. It turns out that because of the way make.py calls sphinx-build, which itself calls python, my local build of matplotlib is not being picked up, and instead I'm getting the old globally installed version (in fact, this had nothing to do with our make.py, I get the same problem calling sphinx-build directly. Adding sys.path.insert(0, '../lib/') to conf.py did the trick though.

Now building these docs. Once I've done that, I'll merge this and then rebase my conflicting branch.

For the record, I've also been getting the following:

writing output... [  0%] api/artist_api                                                                                                               
Exception occurred:
  File "Sphinx-1.1.3-py2.7.egg/sphinx/ext/graphviz.py", line 219, in render_dot_html
    mapfile = open(outfn + '.map', 'rb')
IOError: [Errno 2] No such file or directory: 'doc/build/html/_images/inheritance-e7d27e10673ff7b93cbe7104e04dbb29a26587da.png.map'
The full traceback has been saved in /var/tmp/sphinx-err-JmhgQ8.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!
Building HTML failed.

Which I fixed by downgrading from graphiviz 2.30 back to 2.26 (because I had it handy, but otherwise 2.28).

I notice Lena has made her way back into the gallery. @tonysyu - would you mind creating a follow on PR to use the Grace Hopper image instead?

@tonysyu - would mind also putting up another separate PR which fixes backend_driver.py?

@pelson: My solution to the build-sphinx script pointing to the wrong Python is to install Sphinx into the same virtualenv as where I installed matplotlib. Adding ../lib to sys.path will only work for pure Python modules -- C/C++ extentsions don't live there so won't be included.