8000 Clean up legend loc parameter documentation · matplotlib/matplotlib@53691a5 · GitHub
[go: up one dir, main page]
Skip to content

Commit 53691a5

Browse files
QuLogicQuLogic
committed
Clean up legend loc parameter documentation
As we now have different docs for the *loc* parameter to `Figure/Axes.legend`, we can replace the ambiguous 'axes/figure' with the correct type. And also remove 'best' from the `Figure.legend` version. Note, I did not remove 'best' from the numerical table, as that would be annoying to do, so I just annotated it. Fixes ##25323
1 parent 430fb1d commit 53691a5

File tree

2 files changed

+48
-56
lines changed

2 files changed

+48
-56
lines changed

‎lib/matplotlib/figure.py

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1102,7 +1102,6 @@ def legend(self, *args, **kwargs):
11021102
----------------
11031103
%(_legend_kw_figure)s
11041104
1105-
11061105
See Also
11071106
--------
11081107
.Axes.legend

‎lib/matplotlib/legend.py

Lines changed: 48 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -158,8 +158,7 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
158158
same height, set to ``[0.5]``.
159159
160160
ma 10000 rkerscale : float, default: :rc:`legend.markerscale`
161-
The relative size of legend markers compared with the originally
162-
drawn ones.
161+
The relative size of legend markers compared to the originally drawn ones.
163162
164163
markerfirst : bool, default: True
165164
If *True*, legend marker is placed to the left of the legend label.
@@ -254,52 +253,55 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
254253
"""
255254

256255
_loc_doc_base = """
257-
loc : str or pair of floats, {0}
256+
loc : str or pair of floats, default: {default}
258257
The location of the legend.
259258
260-
The strings
261-
``'upper left', 'upper right', 'lower left', 'lower right'``
262-
place the legend at the corresponding corner of the axes/figure.
259+
The strings ``'upper left'``, ``'upper right'``, ``'lower left'``,
260+
``'lower right'`` place the legend at the corresponding corner of the
261+
{parent}.
263262
264-
The strings
265-
``'upper center', 'lower center', 'center left', 'center right'``
266-
place the legend at the center of the corresponding edge of the
267-
axes/figure.
268-
269-
The string ``'center'`` places the legend at the center of the axes/figure.
270-
271-
The string ``'best'`` places the legend at the location, among the nine
272-
locations defined so far, with the minimum overlap with other drawn
273-
artists. This option can be quite slow for plots with large amounts of
274-
data; your plotting speed may benefit from providing a specific location.
263+
The strings ``'upper center'``, ``'lower center'``, ``'center left'``,
264+
``'center right'`` place the legend at the center of the corresponding edge
265+
of the {parent}.
275266
267+
The string ``'center'`` places the legend at the center of the {parent}.
268+
{best}
276269
The location can also be a 2-tuple giving the coordinates of the lower-left
277-
corner of the legend in axes coordinates (in which case *bbox_to_anchor*
270+
corner of the legend in {parent} coordinates (in which case *bbox_to_anchor*
278271
will be ignored).
279272
280273
For back-compatibility, ``'center right'`` (but no other location) can also
281-
be spelled ``'right'``, and each "string" locations can also be given as a
274+
be spelled ``'right'``, and each "string" location can also be given as a
282275
numeric value:
283276
284-
=============== =============
285-
Location String Location Code
286-
=============== =============
287-
'best' 0
288-
'upper right' 1
289-
'upper left' 2
290-
'lower left' 3
291-
'lower right' 4
292-
'right' 5
293-
'center left' 6
294-
'center right' 7
295-
'lower center' 8
296-
'upper center' 9
297-
'center' 10
298-
=============== =============
299-
{1}"""
300-
301-
_legend_kw_axes_st = (_loc_doc_base.format("default: :rc:`legend.loc`", '') +
302-
_legend_kw_doc_base)
277+
================== =============
278+
Location String Location Code
279+
================== =============
280+
'best' (Axes only) 0
281+
'upper right' 1
282+
'upper left' 2
283+
'lower left' 3
284+
'lower right' 4
285+
'right' 5
286+
'center left' 6
287+
'center right' 7
288+
'lower center' 8
289+
'upper center' 9
290+
'center' 10
291+
================== =============
292+
{outside}"""
293+
294+
_loc_doc_best = """
295+
The string ``'best'`` places the legend at the location, among the nine
296+
locations defined so far, with the minimum overlap with other drawn
297+
artists. This option can be quite slow for plots with large amounts of
298+
data; your plotting speed may benefit from providing a specific location.
299+
"""
300+
301+
_legend_kw_axes_st = (
302+
_loc_doc_base.format(parent='axes', default=':rc:`legend.loc`',
303+
best=_loc_doc_best, outside='') +
304+
_legend_kw_doc_base)
303305
_docstring.interpd.update(_legend_kw_axes=_legend_kw_axes_st)
304306

305307
_outside_doc = """
@@ -314,21 +316,23 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
314316
:doc:`/tutorials/intermediate/legend_guide` for more details.
315317
"""
316318

317-
_legend_kw_figure_st = (_loc_doc_base.format("default: 'upper right'",
318-
_outside_doc) +
319-
_legend_kw_doc_base)
319+
_legend_kw_figure_st = (
320+
_loc_doc_base.format(parent='figure', default="'upper right'",
321+
best='', outside=_outside_doc) +
322+
_legend_kw_doc_base)
320323
_docstring.interpd.update(_legend_kw_figure=_legend_kw_figure_st)
321324

322325
_legend_kw_both_st = (
323-
_loc_doc_base.format("default: 'best' for axes, 'upper right' for figures",
324-
_outside_doc) +
326+
_loc_doc_base.format(parent='axes/figure',
327+
default=":rc:`legend.loc` for Axes, 'upper right' for Figure",
328+
best=_loc_doc_best, outside=_outside_doc) +
325329
_legend_kw_doc_base)
326330
_docstring.interpd.update(_legend_kw_doc=_legend_kw_both_st)
327331

328332

329333
class Legend(Artist):
330334
"""
331-
Place a legend on the axes at location loc.
335+
Place a legend on the figure/axes.
332336
"""
333337

334338
# 'best' is only implemented for axes legends
@@ -407,17 +411,6 @@ def __init__(
407411
List of `.Artist` objects added as legend entries.
408412
409413
.. versionadded:: 3.7
410-
411-
Notes
412-
-----
413-
Users can specify any arbitrary location for the legend using the
414-
*bbox_to_anchor* keyword argument. *bbox_to_anchor* can be a
6957 415-
`.BboxBase` (or derived there from) or a tuple of 2 or 4 floats.
416-
See `set_bbox_to_anchor` for more detail.
417-
418-
The legend location can be specified by setting *loc* with a tuple of
419-
2 floats, which is interpreted as the lower-left corner of the legend
420-
in the normalized axes coordinate.
421414
"""
422415
# local import only to avoid circularity
423416
from matplotlib.axes import Axes

0 commit comments

Comments
 (0)
0