Skip to content

Cleanup patches docstrings. #16196

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 1 commit into from
Jan 12, 2020
Merged

Cleanup patches docstrings. #16196

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
105 changes: 46 additions & 59 deletions lib/matplotlib/patches.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,9 +99,8 @@ def get_verts(self):
"""
Return a copy of the vertices used in this patch.

If the patch contains Bezier curves, the curves will be
interpolated by line segments. To access the curves as
curves, use :meth:`get_path`.
If the patch contains Bezier curves, the curves will be interpolated by
line segments. To access the curves as curves, use `get_path`.
"""
trans = self.get_transform()
path = self.get_path()
Expand Down Expand Up @@ -263,15 +262,15 @@ def get_transform(self):

def get_data_transform(self):
"""
Return the :class:`~matplotlib.transforms.Transform` instance which
maps data coordinates to physical coordinates.
Return the `~.transforms.Transform` mapping data coordinates to
physical coordinates.
"""
return artist.Artist.get_transform(self)

def get_patch_transform(self):
"""
Return the :class:`~matplotlib.transforms.Transform` instance which
takes patch coordinates to data coordinates.
Return the `~.transforms.Transform` instance mapping patch coordinates
to data coordinates.

For example, one may define a patch of a circle which represents a
radius of 5 by providing coordinates for a unit circle, and a
Expand Down Expand Up @@ -968,7 +967,7 @@ def __str__(self):
@docstring.dedent_interpd
def __init__(self, path, **kwargs):
"""
*path* is a :class:`matplotlib.path.Path` object.
*path* is a `~.path.Path` object.

Valid keyword arguments are:

Expand Down Expand Up @@ -1211,9 +1210,9 @@ def __init__(self, x, y, dx, dy, width=1.0, **kwargs):

See Also
--------
:class:`FancyArrow` :
FancyArrow
Patch that allows independent control of the head and tail
properties
properties.
"""
super().__init__(**kwargs)
self._patch_transform = (
Expand Down Expand Up @@ -1349,9 +1348,9 @@ def __init__(self, xy, radius=5,
** kwargs):
"""
Create a circle at *xy* = (*x*, *y*) with given *radius*.
This circle is approximated by a regular polygon with
*resolution* sides. For a smoother circle drawn with splines,
see :class:`~matplotlib.patches.Circle`.

This circle is approximated by a regular polygon with *resolution*
sides. For a smoother circle drawn with splines, see `Circle`.

Valid keyword arguments are:

Expand Down Expand Up @@ -1463,10 +1462,10 @@ def __str__(self):
@docstring.dedent_interpd
def __init__(self, xy, radius=5, **kwargs):
"""
Create true circle at center *xy* = (*x*, *y*) with given
*radius*. Unlike :class:`~matplotlib.patches.CirclePolygon`
which is a polygonal approximation, this uses Bezier splines
and is much closer to a scale-free circle.
Create a true circle at center *xy* = (*x*, *y*) with given *radius*.

Unlike `CirclePolygon` which is a polygonal approximation, this uses
Bezier splines and is much closer to a scale-free circle.

Valid keyword arguments are:

Expand Down Expand Up @@ -1503,7 +1502,7 @@ class Arc(Ellipse):

- The arc cannot be filled.

- The arc must be used in an :class:`~.axes.Axes` instance---it can not be
- The arc must be used in an `~.axes.Axes` instance---it can not be
added directly to a `.Figure`---because it is optimized to only render
the segments that are inside the axes bounding box with high resolution.
"""
Expand Down Expand Up @@ -1605,8 +1604,7 @@ def draw(self, renderer):
3. Proceeding counterclockwise starting in the positive
x-direction, each of the visible arc-segments between the
pairs of vertices are drawn using the Bezier arc
approximation technique implemented in
:meth:`matplotlib.path.Path.arc`.
approximation technique implemented in `.Path.arc`.
"""
if not hasattr(self, 'axes'):
raise RuntimeError('Arcs can only be used in Axes instances')
Expand Down Expand Up @@ -1705,8 +1703,7 @@ def segment_circle_intersect(x0, y0, x1, y1):
def bbox_artist(artist, renderer, props=None, fill=True):
"""
This is a debug function to draw a rectangle around the bounding
box returned by
:meth:`~matplotlib.artist.Artist.get_window_extent` of an artist,
box returned by an artist's `.Artist.get_window_extent`
to test whether the artist is returning the correct bbox.

*props* is a dict of rectangle props with the additional property
Expand Down Expand Up @@ -1737,8 +1734,7 @@ def bbox_artist(artist, renderer, props=None, fill=True):
def draw_bbox(bbox, renderer, color='k', trans=None):
"""
This is a debug function to draw a rectangle around the bounding
box returned by
:meth:`~matplotlib.artist.Artist.get_window_extent` of an artist,
box returned by an artist's `.Artist.get_window_extent`
to test whether the artist is returning the correct bbox.
"""

Expand Down Expand Up @@ -1857,8 +1853,8 @@ def _register_style(style_list, cls=None, *, name=None):

class BoxStyle(_Style):
"""
:class:`BoxStyle` is a container class which defines several
boxstyle classes, which are used for :class:`FancyBboxPatch`.
`BoxStyle` is a container class which defines several
boxstyle classes, which are used for `FancyBboxPatch`.

A style object can be created as::

Expand Down Expand Up @@ -2627,10 +2623,9 @@ def get_bbox(self):

class ConnectionStyle(_Style):
"""
:class:`ConnectionStyle` is a container class which defines
`ConnectionStyle` is a container class which defines
several connectionstyle classes, which is used to create a path
between two points. These are mainly used with
:class:`FancyArrowPatch`.
between two points. These are mainly used with `FancyArrowPatch`.

A connectionstyle object can be either created as::

Expand Down Expand Up @@ -3071,9 +3066,9 @@ def _point_along_a_line(x0, y0, x1, y1, d):

class ArrowStyle(_Style):
"""
:class:`ArrowStyle` is a container class which defines several
`ArrowStyle` is a container class which defines several
arrowstyle classes, which is used to create an arrow path along a
given path. These are mainly used with :class:`FancyArrowPatch`.
given path. These are mainly used with `FancyArrowPatch`.

A arrowstyle object can be either created as::

Expand All @@ -3099,7 +3094,7 @@ class ArrowStyle(_Style):
and it returns a tuple of a `.Path` instance and a boolean
value. *path* is a `.Path` instance along which the arrow
will be drawn. *mutation_size* and *aspect_ratio* have the same
meaning as in :class:`BoxStyle`. *linewidth* is a line width to be
meaning as in `BoxStyle`. *linewidth* is a line width to be
stroked. This is meant to be used to correct the location of the
head so that it does not overshoot the destination point, but not all
classes support it.
Expand Down Expand Up @@ -3854,7 +3849,7 @@ def transmute(self, path, mutation_size, linewidth):

class FancyArrowPatch(Patch):
"""
A fancy arrow patch. It draws an arrow using the :class:`ArrowStyle`.
A fancy arrow patch. It draws an arrow using the `ArrowStyle`.

The head and tail positions are fixed at the specified start and end points
of the arrow, but the size and shape (in display coordinates) of the arrow
Expand Down Expand Up @@ -3906,12 +3901,11 @@ def __init__(self, posA=None, posB=None,
*patchB*, *shrinkA*, and *shrinkB* are ignored.

arrowstyle : str or `.ArrowStyle`, default: 'simple'
Describes how the fancy arrow will be
drawn. It can be string of the available arrowstyle names,
with optional comma-separated attributes, or an
:class:`ArrowStyle` instance. The optional attributes are meant to
be scaled with the *mutation_scale*. The following arrow styles are
available:
The `.ArrowStyle` with which the fancy arrow is drawn. If a
string, it should be one of the available arrowstyle names, with
optional comma-separated attributes. The optional attributes are
meant to be scaled with the *mutation_scale*. The following arrow
styles are available:

%(AvailableArrowstyles)s

Expand All @@ -3920,19 +3914,18 @@ def __init__(self, posA=None, posB=None,

connectionstyle : str or `.ConnectionStyle` or None, optional, \
default: 'arc3'
Describes how *posA* and *posB* are connected. It can be an
instance of the :class:`ConnectionStyle` class or a string of the
connectionstyle name, with optional comma-separated attributes. The
following connection styles are available:
The `.ConnectionStyle` with which *posA* and *posB* are connected.
If a string, it should be one of the available connectionstyle
names, with optional comma-separated attributes. The following
connection styles are available:

%(AvailableConnectorstyles)s

connector
Ignored.

patchA, patchB : `.Patch`, default: None
Head and tail patch respectively. :class:`matplotlib.patch.Patch`
instance.
Head and tail patch respectively.

shrinkA, shrinkB : float, default: 2
Shrinking factor of the tail and head of the arrow respectively.
Expand Down Expand Up @@ -4100,9 +4093,7 @@ def set_connectionstyle(self, connectionstyle, **kw):
self.stale = True

def get_connectionstyle(self):
"""
Return the :class:`ConnectionStyle` instance.
"""
"""Return the `ConnectionStyle` used."""
return self._connector

def set_arrowstyle(self, arrowstyle=None, **kw):
Expand Down Expand Up @@ -4244,10 +4235,8 @@ def draw(self, renderer):


class ConnectionPatch(FancyArrowPatch):
"""
A :class:`~matplotlib.patches.ConnectionPatch` class is to make
connecting lines between two points (possibly in different axes).
"""
"""A patch that connects two points (possibly in different axes)."""

def __str__(self):
return "ConnectionPatch((%g, %g), (%g, %g))" % \
(self.xy1[0], self.xy1[1], self.xy2[0], self.xy2[1])
Expand Down Expand Up @@ -4284,7 +4273,7 @@ def __init__(self, xyA, xyB, coordsA, coordsB=None,
shrinkB default is 2 points
mutation_scale default is text size (in points)
mutation_aspect default is 1.
? any key for :class:`matplotlib.patches.PathPatch`
? any key for `matplotlib.patches.PathPatch`
=============== ======================================================

*coordsA* and *coordsB* are strings that indicate the
Expand Down Expand Up @@ -4314,12 +4303,10 @@ def __init__(self, xyA, xyB, coordsA, coordsB=None,

.. note::

Using :class:`~matplotlib.patches.ConnectionPatch` across
two :class:`~matplotlib.axes.Axes` instances is not
directly compatible with :doc:`constrained layout
</tutorials/intermediate/constrainedlayout_guide>`. Add the
artist directly to the :class:`~matplotlib.figure.Figure`
instead of adding it to a specific Axes.
Using `ConnectionPatch` across two `~.axes.Axes` instances
is not directly compatible with :doc:`constrained layout
</tutorials/intermediate/constrainedlayout_guide>`. Add the artist
directly to the `.Figure` instead of adding it to a specific Axes.

.. code-block:: default

Expand Down