DOC: fix docstrings

jklymak · jklymak · commit c5926ad73eca · 2022-12-13T12:15:54.000-08:00
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -283,7 +283,7 @@ def legend(self, *args, **kwargs):
 
         Other Parameters
         ----------------
-        %(_legend_kw_doc)s
+        %(_legend_kw_axes)s
 
         See Also
         --------
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1085,17 +1085,8 @@ def legend(self, *args, **kwargs):
 
         Other Parameters
         ----------------
-        %(_legend_kw_doc)s
-
-        If a figure is using the constrained layout manager, the string codes
-        of the *loc* keyword argument can get better layout behaviour using the
-        prefix 'outside'. There is ambiguity at the corners, so 'outside
-        upper right' will make space for the legend above the rest of the
-        axes in the layout, and 'outside right upper' will make space on the
-        right side of the layout.  In addition to the values of *loc*
-        listed above, we have 'outside right upper', 'outside right lower',
-        'outside left upper', and 'outside left lower'.  See
-        :doc:`/tutorials/intermediate/legend_guide` for more details.
+        %(_legend_kw_figure)s
+
 
         See Also
         --------
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -94,51 +94,7 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
         self.legend.set_bbox_to_anchor(loc_in_bbox)
 
 
-_docstring.interpd.update(_legend_kw_doc="""
-loc : str or pair of floats, default: :rc:`legend.loc` ('best' for axes, \
-'upper right' for figures)
-    The location of the legend.
-
-    The strings
-    ``'upper left', 'upper right', 'lower left', 'lower right'``
-    place the legend at the corresponding corner of the axes/figure.
-
-    The strings
-    ``'upper center', 'lower center', 'center left', 'center right'``
-    place the legend at the center of the corresponding edge of the
-    axes/figure.
-
-    The string ``'center'`` places the legend at the center of the axes/figure.
-
-    The string ``'best'`` places the legend at the location, among the nine
-    locations defined so far, with the minimum overlap with other drawn
-    artists.  This option can be quite slow for plots with large amounts of
-    data; your plotting speed may benefit from providing a specific location.
-
-    The location can also be a 2-tuple giving the coordinates of the lower-left
-    corner of the legend in axes coordinates (in which case *bbox_to_anchor*
-    will be ignored).
-
-    For back-compatibility, ``'center right'`` (but no other location) can also
-    be spelled ``'right'``, and each "string" locations can also be given as a
-    numeric value:
-
-        ===============   =============
-        Location String   Location Code
-        ===============   =============
-        'best'            0
-        'upper right'     1
-        'upper left'      2
-        'lower left'      3
-        'lower right'     4
-        'right'           5
-        'center left'     6
-        'center right'    7
-        'lower center'    8
-        'upper center'    9
-        'center'          10
-        ===============   =============
-
+_legend_kw_doc_base = """
 bbox_to_anchor : `.BboxBase`, 2-tuple, or 4-tuple of floats
     Box that is used to position the legend in conjunction with *loc*.
     Defaults to `axes.bbox` (if called as a method to `.Axes.legend`) or
@@ -289,7 +245,79 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
 
 draggable : bool, default: False
     Whether the legend can be dragged with the mouse.
-""")
+"""
+
+_loc_doc_base = """
+loc : str or pair of floats, {0}
+    The location of the legend.
+
+    The strings
+    ``'upper left', 'upper right', 'lower left', 'lower right'``
+    place the legend at the corresponding corner of the axes/figure.
+
+    The strings
+    ``'upper center', 'lower center', 'center left', 'center right'``
+    place the legend at the center of the corresponding edge of the
+    axes/figure.
+
+    The string ``'center'`` places the legend at the center of the axes/figure.
+
+    The string ``'best'`` places the legend at the location, among the nine
+    locations defined so far, with the minimum overlap with other drawn
+    artists.  This option can be quite slow for plots with large amounts of
+    data; your plotting speed may benefit from providing a specific location.
+
+    The location can also be a 2-tuple giving the coordinates of the lower-left
+    corner of the legend in axes coordinates (in which case *bbox_to_anchor*
+    will be ignored).
+
+    For back-compatibility, ``'center right'`` (but no other location) can also
+    be spelled ``'right'``, and each "string" locations can also be given as a
+    numeric value:
+
+        ===============   =============
+        Location String   Location Code
+        ===============   =============
+        'best'            0
+        'upper right'     1
+        'upper left'      2
+        'lower left'      3
+        'lower right'     4
+        'right'           5
+        'center left'     6
+        'center right'    7
+        'lower center'    8
+        'upper center'    9
+        'center'          10
+        ===============   =============
+    {1}"""
+
+_legend_kw_axes_st = (_loc_doc_base.format("default: :rc:`legend.loc`", '') +
+                      _legend_kw_doc_base)
+_docstring.interpd.update(_legend_kw_axes=_legend_kw_axes_st)
+
+_outside_doc = """
+    If a figure is using the constrained layout manager, the string codes
+    of the *loc* keyword argument can get better layout behaviour using the
+    prefix 'outside'. There is ambiguity at the corners, so 'outside
+    upper right' will make space for the legend above the rest of the
+    axes in the layout, and 'outside right upper' will make space on the
+    right side of the layout.  In addition to the values of *loc*
+    listed above, we have 'outside right upper', 'outside right lower',
+    'outside left upper', and 'outside left lower'.  See
+    :doc:`/tutorials/intermediate/legend_guide` for more details.
+"""
+
+_legend_kw_figure_st = (_loc_doc_base.format("default: 'upper right'",
+                                             _outside_doc) +
+                        _legend_kw_doc_base)
+_docstring.interpd.update(_legend_kw_figure=_legend_kw_figure_st)
+
+_legend_kw_both_st = (
+    _loc_doc_base.format("default: 'best' for axes, 'upper right' for figures",
+                         _outside_doc) +
+    _legend_kw_doc_base)
+_docstring.interpd.update(_legend_kw_doc=_legend_kw_both_st)
 
 
 class Legend(Artist):
