improve docstrings for Axes.bar, Axes.barh, Axes.stackplot #10182
Conversation
|
For easier review: Old docs: New docs: |
lib/matplotlib/axes/_axes.py
Outdated
| (left, right, bottom and top edges) by default. *x*, | ||
| *height*, *width*, and *bottom* can be either scalars or | ||
| sequences. | ||
| (left, right, bottom and top edges) by default. *x*, *height*, |
There was a problem hiding this comment.
would also remove the math markup just before, whose html rendering is a bit unwieldy, and replace it by e.g. inline double-backquotes.
There was a problem hiding this comment.
The sentence is a bit technical anyway. Nobody thinks of a bar plot in terms of rectangle coordinates. Will switch to a more semantic description.
| ``'weighted_wiggle'`` does the same but weights to account for size of | ||
| each layer. It is also called 'Streamgraph'-layout. More details | ||
| can be found at http://leebyron.com/streamgraph/. | ||
| baseline : ['zero' | 'sym' | 'wiggle' | 'weighted_wiggle'] |
There was a problem hiding this comment.
in the doc for y (just above): OR -> or (lowercase)
lib/matplotlib/axes/_axes.py
Outdated
| ``errorbar.capsize`` :data:`rcParam<matplotlib.rcParams>`. | ||
|
|
||
| error_kw : dict, optional | ||
| dictionary of kwargs to be passed to errorbar method. *ecolor* and | ||
| *capsize* may be specified here rather than as independent kwargs. | ||
| Dictionary of kwargs to be passed to the `~.Axes.errorbar()` |
There was a problem hiding this comment.
I think we tend not to include parentheses explicitly (and it would be better to rely on http://www.sphinx-doc.org/en/1.6.5/config.html#confval-add_function_parentheses to set the default doc-wide anyways). Same comment applies throughout.
There was a problem hiding this comment.
I don't agree with this. Explicitly indicating that fill_between is a function has a value. This should be visible also in plain textual docs, e.g. when viewing it in the terminal.
I propose to discuss the strategy here and document whatever the result is in https://github.com/matplotlib/matplotlib/blob/master/doc/devel/documenting_mpl.rst Should I open an issue on this?
There was a problem hiding this comment.
I don't mind discussing the change (well I don't like it but that's another point), but for now grepping for
\(\)`
and manually exluding the cases where it is followed by a second backquote (i.e., actual code samples) in lib/ yields less than 10 cases, whereas I'm pretty certain there's many more cases without parentheses. So unless we agree to switch styles, I'd stick to the version without parentheses.
lib/matplotlib/stackplot.py
Outdated
| r : list | ||
| A list of `PolyCollection`, one for each element in the stacked area | ||
| plot. | ||
| list of `~matplotlib.collections.PolyCollection` |
There was a problem hiding this comment.
The unqualified name (~.PolyCollection) is enough to resolve the class. Same below.
f3ca536 to
3b2b44e
Compare
lib/matplotlib/axes/_axes.py
Outdated
| @@ -1877,102 +1877,88 @@ def bar(self, *args, **kwargs): | |||
| bar(x, height, width, *, align='center', **kwargs) | |||
| bar(x, height, width, bottom, *, align='center', **kwargs) | |||
|
|
|||
| Make a bar plot with rectangles bounded by | |||
| The bars are positioned at *x* with the given *align*ment. Their | |||
There was a problem hiding this comment.
*align*\ ment
(per http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism
In non-URI contexts, backslash-escaped whitespace characters are removed from the document. This allows for character-level inline markup.)
3b2b44e to
40a0dd0
Compare
PR Summary
As part of #10148: Docstring updates for
Axes.bar,Axes.barhandAxes.stackplot.