@@ -98,9 +98,12 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
9898_legend_kw_doc_base = """
9999bbox_to_anchor : `.BboxBase`, 2-tuple, or 4-tuple of floats
100100 Box that is used to position the legend in conjunction with *loc*.
101+ This is an advanced option for free placement of the legend and is
102+ typically used when placing the legend outside of the Axes or at a
103+ custom position. For most use cases, *loc* alone is sufficient.
104+
101105 Defaults to ``axes.bbox`` (if called as a method to `.Axes.legend`) or
102- ``figure.bbox`` (if ``figure.legend``). This argument allows arbitrary
103- placement of the legend.
106+ ``figure.bbox`` (if ``figure.legend``).
104107
105108 Bbox coordinates are interpreted in the coordinate system given by
106109 *bbox_transform*, with the default transform
@@ -119,6 +122,12 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
119122
120123 loc='upper right', bbox_to_anchor=(0.5, 0.5)
121124
125+ For placing the legend outside the Axes, see
126+ `.Figure.legend`, which supports ``'outside right upper'``
127+ and similar location strings.
128+ For more details on legend positioning, see the
129+ :ref:`legend_guide`.
130+
122131ncols : int, default: 1
123132 The number of columns that the legend has.
124133
@@ -265,15 +274,19 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
265274loc : str or pair of floats, default: {default}
266275 The location of the legend.
267276
268- The strings ``'upper left'``, ``'upper right'``, ``'lower left'``,
269- ``'lower right'`` place the legend at the corresponding corner of the
270- {parent} .
277+ The string locations place the legend at the corresponding position
278+ within the bounding box, which by default is the full {parent} area.
279+ The bounding box can be changed via *bbox_to_anchor* .
271280
272- The strings ``'upper center'``, ``'lower center'``, ``'center left'``,
273- ``'center right'`` place the legend at the center of the corresponding edge
274- of the {parent}.
281+ The positions are visualized below::
275282
276- The string ``'center'`` places the legend at the center of the {parent}.
283+ +--------------+--------------+---------------+
284+ | 'upper left' |'upper center'| 'upper right' |
285+ +--------------+--------------+---------------+
286+ |'center left' | 'center' |'center right' |
287+ +--------------+--------------+---------------+
288+ | 'lower left' |'lower center'| 'lower right' |
289+ +--------------+--------------+---------------+
277290{best}
278291 The location can also be a 2-tuple giving the coordinates of the lower-left
279292 corner of the legend in {parent} coordinates (in which case *bbox_to_anchor*
0 commit comments