Repository navigation
Having section "Notes" twice does not raise a warning, but only renders once #64
Description
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.
Activity
tacaswell commentedon Sep 13, 2016
Would the correct behavior here to concatenate the notes sections?
NelleV commentedon Sep 13, 2016
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 commentedon Sep 13, 2016
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 commentedon Sep 13, 2016
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 commentedon Sep 13, 2016
@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 commentedon Sep 13, 2016
@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.
FIX raises an error if a section appears twice
FIX raises an error if a section appears twice