MEP10: adding numpydoc and activating autosummary

[NelleV]

Here is the first step in implementing MEP10 (point 1, and part of point 3)

• Added numpydoc to the sphinx extension
• Added sphinx's autosummary
• Made the output a little prettier (I hope).

Here is the screenshot of a page of the API

I chose to ship numpydoc with matplotlib, instead of asking developpers to install it. That point is debatable.
Also, because of numpydoc, the documentation will not build for sphinx below 1.0.

[pelson]

I chose to ship numpydoc with matplotlib, instead of asking developpers to install it. That point is debatable.

Agreed - I don't think it should be in there personally - it is a reasonable dependency (and since it is a python package is easy enough to install). My only hesitation is in making sure that the error, when a developer doesn't have numpydoc, is a good and clear one.

Nice change @NelleV

[mdboom]

Thanks for taking this on. This is really going to improve things.

I'm of two minds about including numpydoc. One thing to consider is that once #1454 is merged, we can use setuptools to automatically install it for us. But I'm also happy to leave it in and remove it later (should be easy enough to do) if there's enough desire to do so.

[NelleV]

Should we merge it as is, and see whether we want to keep numpydoc? Despite this PR being very preliminary work, I think it would already be a great addition to the docs.

[pelson]

Should we merge it as is, and see whether we want to keep numpydoc?

I feelings on this are to go the other way around. Lets depend on numpydoc rather than ship it and subsequently update docstrings sequentially and systematically in distinct pull requests.

There is no compelling reason to ship numpydoc with mpl, and therefore adding the dependency as part of the codebase adds the possibility, in the future, of diverging versions (in precisely the same way that the plot directive did).

[NelleV]

I've deleted numpydoc from the source code, and I've updated the documentation to mention the dependency on numpydoc. I've also added a check that numpydoc is installed in sphinx's setup file, and raised an import error with a more explicit message on the fact we need it.

[pelson]

Excellent. @mdboom - please merge when your happy. 👍

[mdboom]

Looks good. When #1454 is merged (there's still some puzzling issues with it on Travis), we can make the dependency on numpydoc explicit and pip should install it for us. Until then, I think it's fine to expect developers to have it installed already.

Merging. Thanks for all this work.

[pelson]

This should be numpydoc. I've submitted a PR to fix this.

[pelson]

@NelleV - I'm not getting the nice odd-even colour scheme with the method table - I the classes of my table rows are row-odd and row-even. Is this a numpydoc version issue do you think? I've got numpydoc 0.4 from pypi (which doesn't have a numpydoc.__version__ attribute).

[pelson]

I'm also getting two method tables for Figure, but only one for AxesStack (in build/html/api/figure_api.html?highlight=figure#matplotlib.figure.AxesStack).

Any tips?

[NelleV]

@pelson I'm not sure.. What version of sphinx are you using?
It works well on my computer. I also have numpydoc 0.4

[pelson]

Sphinx 1.1.3.

[NelleV]

@pelson Same here. Have you made a "python make.py clean" before rebuilding the documentation ?