improve Axes.stem docstring #10154
improve Axes.stem docstring #10154
Conversation
lib/matplotlib/axes/_axes.py
Outdated
| @@ -2392,27 +2392,78 @@ def broken_barh(self, xranges, yrange, **kwargs): | |||
| @_preprocess_data(replace_all_args=True, label_namer=None) | |||
| def stem(self, *args, **kwargs): | |||
| """ | |||
| stem(*args, linefmt=None, markerfmt=None, basefmt=None, data=None, | |||
There was a problem hiding this comment.
Ah, but of course that doesn't work with the doc generation in plt.plotting which tries to parse the first line of the docstring for a summary table (see build failure).
Long term plan should be to fix plt.plotting but in the meantime for this specific case you can hopefully get away with moving stuff into the actual signature...
|
For easier review: Old docs: New docs: |
|
I would just mark the signature using py3 syntax, i.e. and not document kwargs except as a note at the bottom. |
lib/matplotlib/axes/_axes.py
Outdated
| ------- | ||
| a :class:`~matplotlib.container.StemContainer` | ||
|
|
||
| The stemcontainer may be treated like a tuple |
There was a problem hiding this comment.
should probably be indented under "a StemContainer"? rendered version looks wrong otherwise.
lib/matplotlib/container.py
Outdated
| """ | ||
| Container for the artists of bar plots. | ||
|
|
||
| E.g. created in a :meth:`.Axes.bar` plot. |
There was a problem hiding this comment.
This sentence no verb.
Something like
Container for the artists of bar plots (created by `~.Axes.bar`, etc.).
could fit as the first line of the docstring.
Same comment applies throughout PR.
would imply that the *fmt are keyword-only. Quite the opposite is true. They can be optional positional or keyword args. There is no clear syntax for this. Maybe: or ? |
|
Indeed. I think the first form you propose is good though? |
|
Argeed, all changes pushed. |
PR Summary
As part of #10148 and part of the discussion in #10151: Docstring updates for
Axes.stemandcontainer.