8000 Improve docstring of Annoation · matplotlib/matplotlib@97f91ff · GitHub
[go: up one dir, main page]
Skip to content

Commit 97f91ff

Browse files
timhoffmtimhoffm
committed
Improve docstring of Annoation
1 parent 03b07fb commit 97f91ff

File tree

2 files changed

+83
-68
lines changed

2 files changed

+83
-68
lines changed

‎lib/matplotlib/text.py

Lines changed: 82 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1986,107 +1986,115 @@ class Annotation(Text, _AnnotationBase):
19861986
def __str__(self):
19871987
return "Annotation(%g, %g, %r)" % (self.xy[0], self.xy[1], self._text)
19881988

1989-
@docstring.dedent_interpd
19901989
def __init__(self, s, xy,
19911990
xytext=None,
19921991
xycoords='data',
19931992
textcoords=None,
19941993
arrowprops=None,
19951994
annotation_clip=None,
19961995
**kwargs):
1997-
'''
1998-
Annotate the point ``xy`` with text ``s``.
1996+
"""
1997+
Annotate the point *xy* with text *s*.
19991998
2000-
Additional kwargs are passed to `~matplotlib.text.Text`.
1999+
In the simplest form, the text is placed at *xy*.
2000+
2001+
Optionally, the text can be displayed in another position *xytext*.
2002+
An arrow pointing from the text to the annotated point *xy* can then
2003+
be added by defining *arrowprops*.
20012004
20022005
Parameters
20032006
----------
2004-
20052007
s : str
20062008
The text of the annotation.
20072009
2008-
xy : iterable
2009-
Length 2 sequence specifying the *(x,y)* point to annotate.
2010+
xy : (float, float)
2011+
The point *(x,y)* to annotate.
2012+
2013+
xytext : (float, float), optional
2014+
The position *(x,y)* to place the text at.
2015+
If *None*, defaults to *xy*.
2016+
2017+
xycoords : str, `.Artist`, `.Transform`, callable or tuple, optional
20102018
2011-
xytext : iterable, optional
2012-
Length 2 sequence specifying the *(x,y)* to place the text
2013-
at. If None, defaults to ``xy``.
2019+
The coordinate system that *xy* is given in. The following types
2020+
of values are supported:
20142021
2015-
xycoords : str, Artist, Transform, callable or tuple, optional
2022+
- One of the following strings:
20162023
2017-
The coordinate system that ``xy`` is given in.
2024+
================= =============================================
2025+
Value Description
2026+
================= =============================================
2027+
'figure points' Points from the lower left of the figure
2028+
'figure pixels' Pixels from the lower left of the figure
2029+
'figure fraction' Fraction of figure from lower left
2030+
'axes points' Points from lower left corner of axes
2031+
'axes pixels' Pixels from lower left corner of axes
2032+
'axes fraction' Fraction of axes from lower left
2033+
'data' Use the coordinate system of the object being
2034+
annotated (default)
2035+
'polar' *(theta,r)* if not native 'data' coordinates
2036+
================= =============================================
20182037
2019-
For a `str` the allowed values are:
2038+
- An `.Artist`: *xy* is interpreted as a fraction of the artists
2039+
`~matplotlib.transforms.Bbox`. E.g. *(0, 0)* would be the lower
2040+
left corner of the bounding box and *(0.5, 1)* would be the
2041+
center top of the bounding box.
20202042
2021-
================= ===============================================
2022-
Property Description
2023-
================= ===============================================
2024-
'figure points' points from the lower left of the figure
2025-
'figure pixels' pixels from the lower left of the figure
2026-
'figure fraction' fraction of figure from lower left
2027-
'axes points' points from lower left corner of axes
2028-
'axes pixels' pixels from lower left corner of axes
2029-
'axes fraction' fraction of axes from lower left
2030-
'data' use the coordinate system of the object being
2031-
annotated (default)
2032-
'polar' *(theta,r)* if not native 'data' coordinates
2033-
================= ===============================================
2043+
- A `.Transform` to transform *xy* to screen coordinates.
20342044
2035-
If a `~matplotlib.artist.Artist` object is passed in the units are
2036-
fraction if it's bounding box.
2045+
- A function with one of the following signatures::
20372046
2038-
If a `~matplotlib.transforms.Transform` object is passed
2039-
in use that to transform ``xy`` to screen coordinates
2047+
def transform(renderer) -> Bbox
2048+
def transform(renderer) -> Transform
20402049
2041-
If a callable it must take a
2042-
`~matplotlib.backend_bases.RendererBase` object as input
2043-
and return a `~matplotlib.transforms.Transform` or
2044-
`~matplotlib.transforms.Bbox` object
2050+
where *renderer* is a `.RendererBase` subclass.
20452051
2046-
If a `tuple` must be length 2 tuple of str, `Artist`,
2047-
`Transform` or callable objects. The first transform is
2048-
used for the *x* coordinate and the second for *y*.
2052+
The result of the function is interpreted like the `.Artist` and
2053+
`.Transform` cases above.
2054+
2055+
- A tuple *(xcoords, ycoords)* specifying separate coordinate
2056+
systems for *x* and *y*. *xcoords* and *ycoords* must each be
2057+
of one of the above described types.
20492058
20502059
See :ref:`plotting-guide-annotation` for more details.
20512060
2052-
Defaults to ``'data'``
2061+
Defaults to 'data'.
20532062
2054-
textcoords : str, `Artist`, `Transform`, callable or tuple, optional
2055-
The coordinate system that ``xytext`` is given, which
2056-
may be different than the coordinate system used for
2057-
``xy``.
2063+
textcoords : str, `.Artist`, `.Transform`, callable or tuple, optional
2064+
The coordinate system that *xytext* is given in.
20582065
2059-
All ``xycoords`` values are valid as well as the following
2066+
All *xycoords* values are valid as well as the following
20602067
strings:
20612068
20622069
================= =========================================
2063-
Property Description
2070+
Value Description
20642071
================= =========================================
2065-
'offset points' offset (in points) from the *xy* value
2066-
'offset pixels' offset (in pixels) from the *xy* value
2072+
'offset points' Offset (in points) from the *xy* value
2073+
'offset pixels' Offset (in pixels) from the *xy* value
20672074
================= =========================================
20682075
2069-
defaults to the input of ``xycoords``
2076+
Defaults to the value of *xycoords*, i.e. use the same coordinate
2077+
system for annotation point and text position.
20702078
20712079
arrowprops : dict, optional
2072-
If not None, properties used to draw a
2073-
`~matplotlib.patches.FancyArrowPatch` arrow between ``xy`` and
2074-
``xytext``.
2080+
The properties used to draw a
2081+
`~matplotlib.patches.FancyArrowPatch` arrow between the
2082+
positions *xy* and *xytext*.
20752083
2076-
If `arrowprops` does not contain the key ``'arrowstyle'`` the
2084+
If *arrowprops* does not contain the key 'arrowstyle' the
20772085
allowed keys are:
20782086
20792087
========== ======================================================
20802088
Key Description
20812089
========== ======================================================
2082-
width the width of the arrow in points
2083-
headwidth the width of the base of the arrow head in points
2084-
headlength the length of the arrow head in points
2085-
shrink fraction of total length to 'shrink' from both ends
2086-
? any key to :class:`matplotlib.patches.FancyArrowPatch`
2090+
width The width of the arrow in points
2091+
headwidth The width of the base of the arrow head in points
2092+
headlength The length of the arrow head in points
2093+
shrink Fraction of total length to shrink from both ends
2094+
? Any key to :class:`matplotlib.patches.FancyArrowPatch`
20872095
========== ======================================================
20882096
2089-
If the `arrowprops` contains the key ``'arrowstyle'`` the
2097+
If *arrowprops* contains the key 'arrowstyle' the
20902098
above keys are forbidden. The allowed values of
20912099
``'arrowstyle'`` are:
20922100
@@ -2124,25 +2132,32 @@ def __init__(self, s, xy,
21242132
? any key for :class:`matplotlib.patches.PathPatch`
21252133
=============== ==================================================
21262134
2127-
Defaults to None
2135+
Defaults to None, i.e. no arrow is drawn.
21282136
2129-
annotation_clip : bool, optional
2130-
Controls the visibility of the annotation when it goes
2137+
annotation_clip : bool or None, optional
2138+
Whether to draw the annotation when the annotation point *xy* is
21312139
outside the axes area.
21322140
2133-
If `True`, the annotation will only be drawn when the
2134-
``xy`` is inside the axes. If `False`, the annotation will
2135-
always be drawn regardless of its position.
2141+
- If *True*, the annotation will only be drawn when *xy* is
2142+
within the axes.
2143+
- If *False*, the annotation will always be drawn.
2144+
- If *None*, the annotation will only be drawn when *xy* is
2145+
within the axes and *xycoords* is 'data'.
2146+
2147+
Defaults to *None*.
21362148
2137-
The default is `None`, which behave as `True` only if
2138-
*xycoords* is "data".
2149+
**kwargs
2150+
Additional kwargs are passed to `~matplotlib.text.Text`.
21392151
21402152
Returns
21412153
-------
2142-
Annotation
2154+
annotation : `.Annotation`
21432155
2144-
'''
2156+
See Also
2157+
--------
2158+
:ref:`plotting-guide-annotation`.
21452159
2160+
"""
21462161
_AnnotationBase.__init__(self,
21472162
xy,
21482163
xycoords=xycoords,

‎lib/mpl_toolkits/axes_grid1/axes_divider.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -359,7 +359,7 @@ def __init__(self, fig, *args, horizontal=None, vertical=None,
359359
aspect=None, anchor='C'):
360360
"""
361361
Parameters
362-
----------
362+
----------^
363363
fig : :class:`matplotlib.figure.Figure`
364364
args : tuple (*numRows*, *numCols*, *plotNum*)
365365
The array of subplots in the figure has dimensions *numRows*,

0 commit comments

Comments
 (0)
0