From da1763c1b63d8b694e7c5d7a0f2a1151f63eec42 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Thu, 15 Mar 2018 12:16:39 -0700 Subject: [PATCH 1/3] DOC: make legend docstring interpolated --- lib/matplotlib/axes/_axes.py | 167 +-------------------------- lib/matplotlib/figure.py | 167 +-------------------------- lib/matplotlib/legend.py | 169 +--------------------------- lib/matplotlib/tests/test_legend.py | 34 ------ 4 files changed, 4 insertions(+), 533 deletions(-) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index b40294173701..0e7dad239d23 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -363,172 +363,7 @@ def legend(self, *args, **kwargs): Other Parameters ---------------- - loc : int or string or pair of floats, default: 'upper right' - The location of the legend. Possible codes are: - - =============== ============= - 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 - =============== ============= - - - Alternatively can be a 2-tuple giving ``x, y`` of the lower-left - corner of the legend in axes coordinates (in which case - ``bbox_to_anchor`` will be ignored). - - bbox_to_anchor : `.BboxBase` or pair of floats - Specify any arbitrary location for the legend in `bbox_transform` - coordinates (default Axes coordinates). - - For example, to put the legend's upper right hand corner in the - center of the axes the following keywords can be used:: - - loc='upper right', bbox_to_anchor=(0.5, 0.5) - - ncol : integer - The number of columns that the legend has. Default is 1. - - prop : None or :class:`matplotlib.font_manager.FontProperties` or dict - The font properties of the legend. If None (default), the current - :data:`matplotlib.rcParams` will be used. - - fontsize : int or float or {'xx-small', 'x-small', 'small', 'medium', \ -'large', 'x-large', 'xx-large'} - Controls the font size of the legend. If the value is numeric the - size will be the absolute font size in points. String values are - relative to the current default font size. This argument is only - used if `prop` is not specified. - - numpoints : None or int - The number of marker points in the legend when creating a legend - entry for a `.Line2D` (line). - Default is ``None``, which will take the value from - :rc:`legend.numpoints`. - - scatterpoints : None or int - The number of marker points in the legend when creating - a legend entry for a `.PathCollection` (scatter plot). - Default is ``None``, which will take the value from - :rc:`legend.scatterpoints`. - - scatteryoffsets : iterable of floats - The vertical offset (relative to the font size) for the markers - created for a scatter plot legend entry. 0.0 is at the base the - legend text, and 1.0 is at the top. To draw all markers at the - same height, set to ``[0.5]``. Default is ``[0.375, 0.5, 0.3125]``. - - markerscale : None or int or float - The relative size of legend markers compared with the originally - drawn ones. - Default is ``None``, which will take the value from - :rc:`legend.markerscale`. - - markerfirst : bool - If *True*, legend marker is placed to the left of the legend label. - If *False*, legend marker is placed to the right of the legend - label. - Default is *True*. - - frameon : None or bool - Control whether the legend should be drawn on a patch - (frame). - Default is ``None``, which will take the value from - :rc:`legend.frameon`. - - fancybox : None or bool - Control whether round edges should be enabled around the - :class:`~matplotlib.patches.FancyBboxPatch` which makes up the - legend's background. - Default is ``None``, which will take the value from - :rc:`legend.fancybox`. - - shadow : None or bool - Control whether to draw a shadow behind the legend. - Default is ``None``, which will take the value from - :rc:`legend.shadow`. - - framealpha : None or float - Control the alpha transparency of the legend's background. - Default is ``None``, which will take the value from - :rc:`legend.framealpha`. If shadow is activated and - *framealpha* is ``None``, the default value is ignored. - - facecolor : None or "inherit" or a color spec - Control the legend's background color. - Default is ``None``, which will take the value from - :rc:`legend.facecolor`. If ``"inherit"``, it will take - :rc:`axes.facecolor`. - - edgecolor : None or "inherit" or a color spec - Control the legend's background patch edge color. - Default is ``None``, which will take the value from - :rc:`legend.edgecolor` If ``"inherit"``, it will take - :rc:`axes.edgecolor`. - - mode : {"expand", None} - If `mode` is set to ``"expand"`` the legend will be horizontally - expanded to fill the axes area (or `bbox_to_anchor` if defines - the legend's size). - - bbox_transform : None or :class:`matplotlib.transforms.Transform` - The transform for the bounding box (`bbox_to_anchor`). For a value - of ``None`` (default) the Axes' - :data:`~matplotlib.axes.Axes.transAxes` transform will be used. - - title : str or None - The legend's title. Default is no title (``None``). - - borderpad : float or None - The fractional whitespace inside the legend border. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.borderpad`. - - labelspacing : float or None - The vertical space between the legend entries. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.labelspacing`. - - handlelength : float or None - The length of the legend handles. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.handlelength`. - - handletextpad : float or None - The pad between the legend handle and text. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.handletextpad`. - - borderaxespad : float or None - The pad between the axes and legend border. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.borderaxespad`. - - columnspacing : float or None - The spacing between columns. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.columnspacing`. - - handler_map : dict or None - The custom dictionary mapping instances or types to a legend - handler. This `handler_map` updates the default handler map - found at :func:`matplotlib.legend.Legend.get_legend_handler_map`. + %(_legend_kw_doc)s Returns ------- diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 4f8a8f642377..a9d405f80d19 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1574,172 +1574,7 @@ def legend(self, *args, **kwargs): Other Parameters ---------------- - loc : int or string or pair of floats, default: 'upper right' - The location of the legend. Possible codes are: - - =============== ============= - 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 - =============== ============= - - - Alternatively can be a 2-tuple giving ``x, y`` of the lower-left - corner of the legend in axes coordinates (in which case - ``bbox_to_anchor`` will be ignored). - - bbox_to_anchor : `.BboxBase` or pair of floats - Specify any arbitrary location for the legend in `bbox_transform` - coordinates (default Axes coordinates). - - For example, to put the legend's upper right hand corner in the - center of the axes the following keywords can be used:: - - loc='upper right', bbox_to_anchor=(0.5, 0.5) - - ncol : integer - The number of columns that the legend has. Default is 1. - - prop : None or :class:`matplotlib.font_manager.FontProperties` or dict - The font properties of the legend. If None (default), the current - :data:`matplotlib.rcParams` will be used. - - fontsize : int or float or {'xx-small', 'x-small', 'small', 'medium', \ -'large', 'x-large', 'xx-large'} - Controls the font size of the legend. If the value is numeric the - size will be the absolute font size in points. String values are - relative to the current default font size. This argument is only - used if `prop` is not specified. - - numpoints : None or int - The number of marker points in the legend when creating a legend - entry for a `.Line2D` (line). - Default is ``None``, which will take the value from - :rc:`legend.numpoints`. - - scatterpoints : None or int - The number of marker points in the legend when creating - a legend entry for a `.PathCollection` (scatter plot). - Default is ``None``, which will take the value from - :rc:`legend.scatterpoints`. - - scatteryoffsets : iterable of floats - The vertical offset (relative to the font size) for the markers - created for a scatter plot legend entry. 0.0 is at the base the - legend text, and 1.0 is at the top. To draw all markers at the - same height, set to ``[0.5]``. Default is ``[0.375, 0.5, 0.3125]``. - - markerscale : None or int or float - The relative size of legend markers compared with the originally - drawn ones. - Default is ``None``, which will take the value from - :rc:`legend.markerscale`. - - markerfirst : bool - If *True*, legend marker is placed to the left of the legend label. - If *False*, legend marker is placed to the right of the legend - label. - Default is *True*. - - frameon : None or bool - Control whether the legend should be drawn on a patch - (frame). - Default is ``None``, which will take the value from - :rc:`legend.frameon`. - - fancybox : None or bool - Control whether round edges should be enabled around the - :class:`~matplotlib.patches.FancyBboxPatch` which makes up the - legend's background. - Default is ``None``, which will take the value from - :rc:`legend.fancybox`. - - shadow : None or bool - Control whether to draw a shadow behind the legend. - Default is ``None``, which will take the value from - :rc:`legend.shadow`. - - framealpha : None or float - Control the alpha transparency of the legend's background. - Default is ``None``, which will take the value from - :rc:`legend.framealpha`. If shadow is activated and - *framealpha* is ``None``, the default value is ignored. - - facecolor : None or "inherit" or a color spec - Control the legend's background color. - Default is ``None``, which will take the value from - :rc:`legend.facecolor`. If ``"inherit"``, it will take - :rc:`axes.facecolor`. - - edgecolor : None or "inherit" or a color spec - Control the legend's background patch edge color. - Default is ``None``, which will take the value from - :rc:`legend.edgecolor` If ``"inherit"``, it will take - :rc:`axes.edgecolor`. - - mode : {"expand", None} - If `mode` is set to ``"expand"`` the legend will be horizontally - expanded to fill the axes area (or `bbox_to_anchor` if defines - the legend's size). - - bbox_transform : None or :class:`matplotlib.transforms.Transform` - The transform for the bounding box (`bbox_to_anchor`). For a value - of ``None`` (default) the Axes' - :data:`~matplotlib.axes.Axes.transAxes` transform will be used. - - title : str or None - The legend's title. Default is no title (``None``). - - borderpad : float or None - The fractional whitespace inside the legend border. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.borderpad`. - - labelspacing : float or None - The vertical space between the legend entries. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.labelspacing`. - - handlelength : float or None - The length of the legend handles. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.handlelength`. - - handletextpad : float or None - The pad between the legend handle and text. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.handletextpad`. - - borderaxespad : float or None - The pad between the axes and legend border. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.borderaxespad`. - - columnspacing : float or None - The spacing between columns. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.columnspacing`. - - handler_map : dict or None - The custom dictionary mapping instances or types to a legend - handler. This `handler_map` updates the default handler map - found at :func:`matplotlib.legend.Legend.get_legend_handler_map`. + %(_legend_kw_doc)s Returns ------- diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py index d96327a9de62..ea828728e209 100644 --- a/lib/matplotlib/legend.py +++ b/lib/matplotlib/legend.py @@ -141,7 +141,7 @@ def _update_bbox_to_anchor(self, loc_in_canvas): For example, to put the legend's upper right hand corner in the center of the axes the following keywords can be used:: - loc='upper right', bbox_to_anchor=(0.5, 0.5) + loc='upper right', bbox_to_anchor=(0.5, 0.5) ncol : integer The number of columns that the legend has. Default is 1. @@ -365,172 +365,7 @@ def __init__(self, parent, handles, labels, Other Parameters ---------------- - loc : int or string or pair of floats, default: 'upper right' - The location of the legend. Possible codes are: - - =============== ============= - 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 - =============== ============= - - - Alternatively can be a 2-tuple giving ``x, y`` of the lower-left - corner of the legend in axes coordinates (in which case - ``bbox_to_anchor`` will be ignored). - - bbox_to_anchor : `.BboxBase` or pair of floats - Specify any arbitrary location for the legend in `bbox_transform` - coordinates (default Axes coordinates). - - For example, to put the legend's upper right hand corner in the - center of the axes the following keywords can be used:: - - loc='upper right', bbox_to_anchor=(0.5, 0.5) - - ncol : integer - The number of columns that the legend has. Default is 1. - - prop : None or :class:`matplotlib.font_manager.FontProperties` or dict - The font properties of the legend. If None (default), the current - :data:`matplotlib.rcParams` will be used. - - fontsize : int or float or {'xx-small', 'x-small', 'small', 'medium', \ -'large', 'x-large', 'xx-large'} - Controls the font size of the legend. If the value is numeric the - size will be the absolute font size in points. String values are - relative to the current default font size. This argument is only - used if `prop` is not specified. - - numpoints : None or int - The number of marker points in the legend when creating a legend - entry for a `.Line2D` (line). - Default is ``None``, which will take the value from - :rc:`legend.numpoints`. - - scatterpoints : None or int - The number of marker points in the legend when creating - a legend entry for a `.PathCollection` (scatter plot). - Default is ``None``, which will take the value from - :rc:`legend.scatterpoints`. - - scatteryoffsets : iterable of floats - The vertical offset (relative to the font size) for the markers - created for a scatter plot legend entry. 0.0 is at the base the - legend text, and 1.0 is at the top. To draw all markers at the - same height, set to ``[0.5]``. Default is ``[0.375, 0.5, 0.3125]``. - - markerscale : None or int or float - The relative size of legend markers compared with the originally - drawn ones. - Default is ``None``, which will take the value from - :rc:`legend.markerscale`. - - markerfirst : bool - If *True*, legend marker is placed to the left of the legend label. - If *False*, legend marker is placed to the right of the legend - label. - Default is *True*. - - frameon : None or bool - Control whether the legend should be drawn on a patch - (frame). - Default is ``None``, which will take the value from - :rc:`legend.frameon`. - - fancybox : None or bool - Control whether round edges should be enabled around the - :class:`~matplotlib.patches.FancyBboxPatch` which makes up the - legend's background. - Default is ``None``, which will take the value from - :rc:`legend.fancybox`. - - shadow : None or bool - Control whether to draw a shadow behind the legend. - Default is ``None``, which will take the value from - :rc:`legend.shadow`. - - framealpha : None or float - Control the alpha transparency of the legend's background. - Default is ``None``, which will take the value from - :rc:`legend.framealpha`. If shadow is activated and - *framealpha* is ``None``, the default value is ignored. - - facecolor : None or "inherit" or a color spec - Control the legend's background color. - Default is ``None``, which will take the value from - :rc:`legend.facecolor`. If ``"inherit"``, it will take - :rc:`axes.facecolor`. - - edgecolor : None or "inherit" or a color spec - Control the legend's background patch edge color. - Default is ``None``, which will take the value from - :rc:`legend.edgecolor` If ``"inherit"``, it will take - :rc:`axes.edgecolor`. - - mode : {"expand", None} - If `mode` is set to ``"expand"`` the legend will be horizontally - expanded to fill the axes area (or `bbox_to_anchor` if defines - the legend's size). - - bbox_transform : None or :class:`matplotlib.transforms.Transform` - The transform for the bounding box (`bbox_to_anchor`). For a value - of ``None`` (default) the Axes' - :data:`~matplotlib.axes.Axes.transAxes` transform will be used. - - title : str or None - The legend's title. Default is no title (``None``). - - borderpad : float or None - The fractional whitespace inside the legend border. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.borderpad`. - - labelspacing : float or None - The vertical space between the legend entries. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.labelspacing`. - - handlelength : float or None - The length of the legend handles. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.handlelength`. - - handletextpad : float or None - The pad between the legend handle and text. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.handletextpad`. - - borderaxespad : float or None - The pad between the axes and legend border. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.borderaxespad`. - - columnspacing : float or None - The spacing between columns. - Measured in font-size units. - Default is ``None``, which will take the value from - :rc:`legend.columnspacing`. - - handler_map : dict or None - The custom dictionary mapping instances or types to a legend - handler. This `handler_map` updates the default handler map - found at :func:`matplotlib.legend.Legend.get_legend_handler_map`. + %(_legend_kw_doc)s Notes ----- diff --git a/lib/matplotlib/tests/test_legend.py b/lib/matplotlib/tests/test_legend.py index d5da3608b40e..b11dab6ce836 100644 --- a/lib/matplotlib/tests/test_legend.py +++ b/lib/matplotlib/tests/test_legend.py @@ -14,40 +14,6 @@ import matplotlib.legend as mlegend -# test that docstrings are the same -def get_docstring_section(func, section): - """ extract a section from the docstring of a function """ - ll = inspect.getdoc(func) - lines = ll.splitlines() - insec = False - st = '' - for ind in range(len(lines)): - if lines[ind][:len(section)] == section and lines[ind+1][:3] == '---': - insec = True - ind = ind+1 - if insec: - if len(lines[ind + 1]) > 3 and lines[ind + 1][0:3] == '---': - insec = False - break - else: - st += lines[ind] + '\n' - return st - - -def test_legend_kwdocstrings(): - stax = get_docstring_section(mpl.axes.Axes.legend, 'Parameters') - stfig = get_docstring_section(mpl.figure.Figure.legend, 'Parameters') - assert stfig == stax - - stleg = get_docstring_section(mpl.legend.Legend.__init__, - 'Other Parameters') - stax = get_docstring_section(mpl.axes.Axes.legend, 'Other Parameters') - stfig = get_docstring_section(mpl.figure.Figure.legend, 'Other Parameters') - assert stleg == stax - assert stfig == stax - assert stleg == stfig - - def test_legend_ordereddict(): # smoketest that ordereddict inputs work... From 6888d5dc027c8d7175b6decc01f3363585035d37 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sat, 17 Mar 2018 09:38:01 -0700 Subject: [PATCH 2/3] DOC: fix --- lib/matplotlib/legend.py | 1 - 1 file changed, 1 deletion(-) diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py index ea828728e209..92a121d0adb1 100644 --- a/lib/matplotlib/legend.py +++ b/lib/matplotlib/legend.py @@ -348,7 +348,6 @@ def __init__(self, parent, handles, labels, handler_map=None, ): """ - Parameters ---------- parent : `.Axes` or `.Figure` From ded882227e3737ddcf8bdff3a8a34c272a280695 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sat, 17 Mar 2018 09:59:49 -0700 Subject: [PATCH 3/3] DOC: fix --- lib/matplotlib/legend.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py index 92a121d0adb1..a95080ddea1a 100644 --- a/lib/matplotlib/legend.py +++ b/lib/matplotlib/legend.py @@ -141,7 +141,7 @@ def _update_bbox_to_anchor(self, loc_in_canvas): For example, to put the legend's upper right hand corner in the center of the axes the following keywords can be used:: - loc='upper right', bbox_to_anchor=(0.5, 0.5) + loc='upper right', bbox_to_anchor=(0.5, 0.5) ncol : integer The number of columns that the legend has. Default is 1.