Repository navigation
_preprocess_data interferes in the docstrings Notes section #7095
Description
_preprocess_data interferes with the docstrings Notes section. It appends a Notes section (1) in the wrong section; (2) in the rendering, it overwrites the notes section of the function.
In general, I think matplotlib is trying to be way too smart in appending/replacing stuff in the docstrings. It makes contributing to the documentation (and matplotlib in general) quite hard and often interferes with sphinx or other tools we use. We should try to be more standard.
Activity
story645 commentedon Sep 12, 2016
Which note? If it's
.. note::then that should probably just be folded into the first line, something likeA decorator to add a 'data' kwarg to any a function; also does some input sanitation(yes, this was my fault...sorry)
NelleV commentedon Sep 12, 2016
No, it is the numpydoc section "Notes".
I don't think appending anything would work as expected anyways, as it would be in the wrong section.
You can see the effect it has by comparing the rendered version of scatter: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.scatter
and the docstring in a terminal (or looking at the code). There are two Notes section, and the last one "overwrites" the first one.
Note that the the docstring.Appender also doesn't work as it should in the rendering.
(@docstring.Appender("Addition kwargs: hold = [True|False] overrides default hold state", "\n") shows up at the end of the docstring instead of the of correct section).
Because of all this is very none standard, it makes it hard to identify where the problem comes from.
NelleV commentedon Sep 13, 2016
I have opened a bug on numpydoc for this issue (it should not have been undetected for so long):
numpy/numpydoc#64
efiring commentedon Sep 13, 2016
This is actually critical to having a reasonably polished 2.0. One way to fix it might be to use string interpolation instead of appending the "data" doc block. This would have the advantage of providing full control over where that paragraph goes. It's not clear to me it really belongs in the Notes section anyway.
I agree with @NelleV in being uncomfortable with all the complexity in the present system--not to mention the horrible mess that the interpolated tables of mostly useless artist kwargs leave--but overhauling it is a big project. For 2.0 we must continue to patch it up in its present form. (It might be possible to improve it a little, by using a link instead of endlessly repeating the Line2D kwargs table. And the next incremental improvement would be to replace that automatically-generated table with a less nutty hand-written one. And the next...)
NelleV commentedon Oct 10, 2016
I can fix this by manually updating the different docstrings of that section to reflect the categorical input and remove the automatic appending of the notes section.
It would be a good occasion to add examples as well.
NelleV commentedon Oct 18, 2016
One step closer to 2.0…