Having section "Notes" twice does not raise a warning, but only renders once

[NelleV]

A lot of matplotlib's plotting function have a notes section concatenated to them at runtime. That leads to docstrings such as the following:

(from plt.imshow)

blah blah blah

See also
--------
matshow : Plot a matrix or an array as an image.

Notes
-----
Unless *extent* is used, pixel centers will be located at integer
coordinates. In other words: the origin will coincide with the center
of pixel (0, 0).

Examples
--------

.. plot:: mpl_examples/pylab_examples/image_demo.py

Notes
-----

In addition to the above described arguments, this function can take a
**data** keyword argument. If such a **data** argument is given, the
following arguments are replaced by **data[<arg>]**:

* All positional and all keyword arguments.

Additional kwargs: hold = [True|False] overrides default hold state
"""

The rendered docstring is here: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.imshow
You can notice that the second "Notes" replaced the first one.
And it does this without raising a warning.

[tacaswell]

Would the correct behavior here to concatenate the notes sections?

[NelleV]

I think it should (at least) raise a warning. If I recall correctly, numpydoc requires the sections to be in a specific order, and I think raises a warning when they aren't. But apparently, it doesn't when the section appears twice.
It be great if someone from numpydoc could confirm what the expected behavior is.

[rgommers]

If it's not too hard, I'd be in favor of an exception for that. Because warnings are very hard to spot in the large amount of noise Sphinx tends to generate.

[efiring]

It looks to me like numpydoc can read the sections in arbitrary order; it just looks for sections, identifies what kind they are, and puts each identified section as the value in a dictionary. It might be as easy to append repeats as to raise an exception when a repeat is encountered.

[NelleV]

@rgommers That's very straightforward. I'll create a PR.
I do think that sphinx catches errors and transforms them in warnings, so that's out of our hands.

[NelleV]

@efiring that would be an option (also very easy to do), but I don't think it is a good idea. The docstrings should be as readable in a python terminal as rendered by sphinx, and having several notes section makes it hard to read IMO.