Skip to content

DOC: changed documentation for axvspan to numpydoc format #7267

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 15, 2016
Merged

DOC: changed documentation for axvspan to numpydoc format #7267

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
74b6e1d
DOC changed documentation for axvspan to numpydoc format
Wiolcia Sep 5, 2016
0bc77dc
FIX pep8 compliance
NelleV Oct 13, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 34 additions & 23 deletions lib/matplotlib/axes/_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -862,39 +862,50 @@ def axvspan(self, xmin, xmax, ymin=0, ymax=1, **kwargs):
"""
Add a vertical span (rectangle) across the axes.

Call signature::

axvspan(xmin, xmax, ymin=0, ymax=1, **kwargs)

*x* coords are in data units and *y* coords are in axes (relative
0-1) units.

Draw a vertical span (rectangle) from *xmin* to *xmax*. With
the default values of *ymin* = 0 and *ymax* = 1, this always
Draw a vertical span (rectangle) from `xmin` to `xmax`. With
the default values of `ymin` = 0 and `ymax` = 1. This always
spans the yrange, regardless of the ylim settings, even if you
change them, e.g., with the :meth:`set_ylim` command. That is,
the vertical extent is in axes coords: 0=bottom, 0.5=middle,
1.0=top but the *y* location is in data coordinates.

Return value is the :class:`matplotlib.patches.Polygon`
instance.
1.0=top but the y location is in data coordinates.

Examples:
Parameters
----------
xmin : scalar
Number indicating the first X-axis coordinate of the vertical
span rectangle in data units.
xmax : scalar
Number indicating the second X-axis coordinate of the vertical
span rectangle in data units.
ymin : scalar, optional
Number indicating the first Y-axis coordinate of the vertical
span rectangle in relative Y-axis units (0-1). Default to 0.
ymax : scalar, optional
Number indicating the second Y-axis coordinate of the vertical
span rectangle in relative Y-axis units (0-1). Default to 1.

* draw a vertical green translucent rectangle from x=1.25 to 1.55 that
spans the yrange of the axes::
Returns
-------
rectangle : matplotlib.patches.Polygon
Vertical span (rectangle) from (xmin, ymin) to (xmax, ymax).

>>> axvspan(1.25, 1.55, facecolor='g', alpha=0.5)
Other Parameters
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We're still removing this here?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The consensus is that the links are a better option.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is the general consensus to move away from these, and have nicer documentation on the artists themselves. At least that's what I understood from different conversation, even during the matplotlib call or on tickets.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I may document this in a MEP somewhere.

----------------
**kwargs
Optional parameters are properties of the class
matplotlib.patches.Polygon.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should link?


Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the See Also sections are helpful. But I'd understand if they're a pain to maintain.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It wasn't removed; it just got a numpydoc heading instead of a sphinx one.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ahh yes. I see that now.

Valid kwargs are :class:`~matplotlib.patches.Polygon`
properties:
See Also
--------
axhspan

%(Polygon)s
Examples
--------
Draw a vertical, green, translucent rectangle from x = 1.25 to
x = 1.55 that spans the yrange of the axes.

.. seealso::
>>> axvspan(1.25, 1.55, facecolor='g', alpha=0.5)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the consensus on the style and "completeness" of examples like this?

My thought is that something like:

import matplotlib.pyplot as plt
fig, ax  = plt.subplots()
ax.axvspan(1.25, 1.55, facecolor='g', alpha=0.5)
plt.show()

or a link to the gallery/examples would be better.

I don't feel very strongly about that, though.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that a full runnable example would be much better. I am not a big fan of links in the gallery as they are only good for sphinx rendered documentation, but do not render properly in terminal docstring.


:meth:`axhspan`
for example plot and source code
"""
trans = self.get_xaxis_transform(which='grid')

Expand Down