This looks good -- this is the first time I've spent the time to actually build and look at the output of your MEP10 changes. It looks great -- but sorry if I'm commenting on issues that may have already gone a different way in earlier PRs (such as how the Returns section is written etc.)

For the curious, I just set up an automatic build of the documentation of the master branch of the repository here:
http://cbio.ensmp.fr/~nvaroquaux/matplotlib/doc/ and a check of the flake8 report here (but links don't work):
http://cbio.ensmp.fr/~nvaroquaux/matplotlib/flake8_report/

The flake8 report could be done by shining panda, or something more adapted than bash scripts.

Thanks. Once we get funding in place, I hope to set up a Shining Panda pro account for matplotlib soon -- and this is definitely the kind of useful thing to do over there.

Great. I think it's good (as we doing here) to get the first few docstrings really right and then running through the rest should involve a lot of just following the same pattern.

I think this is ready to be merged.

I'm seeing funky formatting when building this. It looks like "Other Parameters" is divided into two sections...?

Other parameters can have a list of parameter as the "parameters" section has, so I think this is normal.

But why is it on a different background color, with a line above it (unlike Parameters above)? It looks like it's in a different section (at least to my eyes).

It is either the way it is supposed to be or a bug in numpydoc. After digging in numpy and scipy's code, I finnaly found a place where this was used:http://docs.scipy.org/doc/scipy/reference/generated/scipy.weave.inline.html#scipy.weave.inline

There's nothing much we can do about that, except submit a patch to numpydoc.

Ok thanks for looking into it. Since it's not anything we can fix from our end, I'll go ahead and merge this. Thanks.