Also, I'm wondering what's the point of some of the "Call signature" lines in axes/_axes.py because they seem to be redundant?

The Call signature lines probably pre-date sphinx.

It looks like most of those Call signature blocks can be deleted, but there are exceptions such as barbs, quiver, contour, and clabel where there are multiple signatures hidden within *args that Sphinx cannot handle automatically.

I spent a little time looking into the different images, and it seems like, e.g., the tight layout demo, just picks font sizes at random. It makes the doc build a bit unreproducible; can we stop doing that?

I spent a little time looking into the different images, and it seems like, e.g., the tight layout demo, just picks font sizes at random. It makes the doc build a bit unreproducible; can we stop doing that?

Yes! In this case, I don't see any reason why it's random, let's just hardcode the values in the example. In other cases where the example really does want to use random data, we should at least seed the random number generator so the results are predictable.

This needs a rebase.

Yes, waiting for #5769 as well.

I was going to add in fixes to several docstrings with incorrect headings and such, but that might balloon this PR to something rather big. The changes here are enough to get the build to pass without error, so maybe that should be left to some later PR?

Better to not let the prefect be the enemy of the good.

Let's call this done for now then, and I'll work on the other stuff in another PR as time permits.

Should we hold off on this until investigating the bugs @QuLogic alluded to on gitter?

Once we merge the PRs from @jenshnielsen, this should work without warning on Sphinx 1.4. The napoleon_use_param=False setting also makes the bugs go away with 1.3, but there are still some warnings.

I don't know whether or not you still wish to put this on 2.0, but it shouldn't break anything at this point.

Is this something that will ever happen? Folks have been putting a lot of documentation effort in recently. If the standard is supposed to be slightly different it'd be good to know sooner rather than later. If this won't happen, this can be closed?

There are two parts to this: docstring cleanups and the switch to Napoleon. I suspect most of the docstring cleanups have been done by now in other PRs, but I haven't checked. As for the switch to Napoleon, the advantage is that it removes a dependency; the disadvantage is that Napoleon might not perfectly track numpydoc.
@QuLogic, what are your thoughts on this now?

Indeed, most docstring cleanups from here are already merged. #11064 handles the remaining docstring changes, so that this PR can be significantly simplified and focus only on a possible switch to napoleon (or be closed, if there are no longer plans for switching to napoleon).

Closing as it doesn't seem there is any appetite to switch to napoleon. OTOH, if someone wants to take the "switch" part of the PR on, that'd be fine w/ me....

Reopening per #11397 (comment).

If we want to switch to napoleon, we'd need a careful look at the changes that may introduce in the generated files. While technically implementing the same specification, napoleon and numpydoc interpret it differently, sometimes stricter, sometimes more strict. We're probably knowingly and unknowingly adapting our docstrings to the numpydoc interpretation by just using it and checking what works and what doesn't. This "learned" formatting has to be reevaluated when swiching to napoleon.

fwiw, it looks like sklearn (including one of numpydoc's maintainers...) is considering switching to napoleon (scikit-learn/scikit-learn#11440).

But - reading that thread - they are pretty ambiguous about it. The main argument for Napoleon seems to be 'it comes with sphinx' - but that's not a very powerful argument on its own, given that numpydoc is so easy to install.

That's why I said "considering", not "decided".
However I agree with Gael's points:

Is there a long-term reason that Napoleon would get less maintenance than
numpydocs if projects switch to it? It's embedded in sphinx, so it will
get a lot of exposure. Of course, it's a question of community dynamics,
and there is a lot of social in there.

That it's included in sphinx. I tend to hope that it is more likely to
become a community standard. Everybody who does sphinx docs has napoleon.

Sure, but I don't know if it's really true the Napoleon really gets better maintenance. Among the big scientific Python projects, Numpy, Scipy, Pandas, Scikit-image, Scikit-learn, Sympy and Astropy all use Numpydoc, with Statsmodels being the only one I know of that uses Napoleon. Pauli Virtanen leads Scipy, and maintains Numpydoc, so I think it's reasonable to hope it will stay fit for purpose for a while. How about waiting with a plan to review in a year's time?

There are some subtle differences in the parsers concerning name and type detection and formatting.

e.g. numpy/numpydoc#72 (comment)

We now tune the docs to be numpydoc compliant. So we really would have to test how napoleon behaves. Nevertheless, I have the feeling that napoleon has a more sane parser.

I supsect even if we want to switch to napoleon, this PR is so out of date that attempting to rebase it will be more hassle than it's worth; if no-one objects in a week or so I'll close this but leave the issue open.