3.6 doc

3.6.md

@@ -264,3 +264,151 @@ plt.legend([c], ["An ellipse, not a rectangle"],
 + [`pylab_examples` 示例代码: `figlegend_demo.py`](http://matplotlib.org/examples/pylab_examples/figlegend_demo.html#pylab-examples-figlegend-demo)
 + [`pylab_examples` 示例代码: `finance_work2.py`](http://matplotlib.org/examples/pylab_examples/finance_work2.html#pylab-examples-finance-work2)
 + [`pylab_examples` 示例代码: `scatter_symbol.py`](http://matplotlib.org/examples/pylab_examples/scatter_symbol.html#pylab-examples-scatter-symbol)
+
+## `matplotlib.pyplot.legend(*args, **kwargs)` 文档
+
+在轴域上放置一个图例。
+
+为了为轴域上已经存在的线条（例如通过绘图）制作图例，只需使用字符串的可迭代对象（每个图例条目对应一个字符串）调用此函数。 例如：
+
+```py
+ax.plot([1, 2, 3])
+ax.legend(['A simple line'])
+```
+
+但是，为了使『标签』和图例元素实例保持一致，最好在 artist 创建时指定标签，或者通过调用 artist 的`set_label()`方法：
+
+```py
+line, = ax.plot([1, 2, 3], label='Inline label')
+# 通过调用该方法覆写标签
+line.set_label('Label via method')
+ax.legend()
+```
+
+通过定义以下划线开头的标签，可以从图例元素自动选择中排除特定线条。 这对于所有 artist 都是默认的，因此不带任何参数调用`legend()`，并且没有手动设置标签会导致没有绘制图例。
+
+为了完全控制哪些 artist 拥有图例条目，可以传递拥有图例的 artist 的可迭代对象，然后是相应图例标签的可迭代对象：
+
+```py
+legend((line1, line2, line3), ('label1', 'label2', 'label3'))
+```
+
+### 参数
+
+`loc`：整数、字符串或者浮点偶对，默认为`'upper right'`。
+
+图例的位置。 可能的代码是：
+
+|位置字符串 | 位置代码 |
+| --- | --- |
+| `'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` |
+
+或者，可以是一个二元组，提供图例的距离左下角`x, y`坐标（在这种情况下，`bbox_to_anchor`将被忽略）。
+
+`bbox_to_anchor `：`matplotlib.transforms.BboxBase`示例或者浮点元组。
+
+在`bbox_transform`坐标（默认轴域坐标）中为图例指定任意位置。
+
+例如，要将图例的右上角放在轴域中心，可以使用以下关键字：
+
+```py
+loc='upper right', bbox_to_anchor=(0.5, 0.5)
+```
+
+`ncol`：整数。
+
+图例的列数，默认为 1。
+
+`prop`：`None`、`matplotlib.font_manager.FontProperties`或者字典。
+
+图例的字体属性，如果为`None`（默认），会使用当前的` matplotlib.rcParams`。
+
+`fontsize`：整数、浮点或者`{‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’}`。
+
+控制图例的字体大小。 如果值为数字，则大小将为绝对字体大小（以磅为单位）。 字符串值相对于当前默认字体大小。 此参数仅在未指定`prop`的情况下使用。
+
+`numpoints`：`None`或者整数。
+
+为线条/`matplotlib.lines.Line2D`创建图例条目时，图例中的标记点数。 默认值为`None`，它将从`legend.numpoints` `rcParam`中获取值。
+
+`scatterpoints`：`None`或者整数。
+
+为散点图/`matplotlib.collections.PathCollection`创建图例条目时，图例中的标记点数。 默认值为`None`，它将从`legend.scatterpoints` `rcParam`中获取值。
+
+`scatteryoffsets`：浮点的可迭代对象。
+
+为散点图图例条目创建的标记的垂直偏移量（相对于字体大小）。 0.0 是在图例文本的底部，1.0 是在顶部。 为了将所有标记绘制在相同的高度，请设置为`[0.5]`。 默认值为[`0.375,0.5,0.3125]`。
+
+`markerscale`：`None`、整数或者浮点。
+
+图例标记对于原始绘制的标记的相对大小。 默认值为`None`，它将从`legend.markerscale` `rcParam`中获取值。
+
+`markerfirst`: `[ True | False ]`
+
+如果为`True`，则图例标记位于图例标签的左侧，如果为`False`，图例标记位于图例标签的右侧。
+
+`frameon`：`None`或布尔值
+
+控制是否应在图例周围绘制框架。 默认值为`None`，它将从`legend.frameon` `rcParam`中获取值。
+
+`fancybox`：`None`或布尔值
+
+控制是否应在构成图例背景的`FancyBboxPatch`周围启用圆边。 默认值为`None`，它将从`legend.fancybox` `rcParam`中获取值。
+
+`shadow`：`None`或布尔值
+
+控制是否在图例后面画一个阴影。 默认值为`None`，它将从`legend.shadow` `rcParam`中获取值。
+
+`framealpha`：`None`或浮点
+
+控制图例框架的 Alpha 透明度。 默认值为`None`，它将从`legend.framealpha` `rcParam`中获取值。
+
+`mode`：`{"expand", None}`
+
+如果`mode`设置为`"expand"`，图例将水平扩展来填充轴域区域（如果定义图例的大小，则为`bbox_to_anchor`）。
+
+`bbox_transform`：`None`或者` matplotlib.transforms.Transform`
+
+边界框的变换（`bbox_to_anchor`）。 对于`None`值（默认），将使用`Axes`的`transAxes`变换。
+
+`title`：字符串或者`None`
+
+图例的标题，默认没有标题（`None`）。
+
+`borderpad`：浮点或`None`
+
+图例边框的内边距。 以字体大小为单位度量。 默认值为`None`，它将从`legend.borderpad` `rcParam`中获取值。
+
+`labelspacing`：浮点或`None`
+
+图例条目之间的垂直间距。 以字体大小为单位度量。 默认值为`None`，它将从`legend.labelspacing` `rcParam`中获取值。
+
+`handlelength`：浮点或`None`
+
+图例句柄的长度。 以字体大小为单位度量。 默认值为`None`，它将从`legend.handlelength` `rcParam`取值。
+
+`handletextpad`：浮点或`None`
+
+图例句柄和文本之间的间距。 以字体大小为单位度量。 默认值为`None`，它将从`legend.handletextpad` `rcParam`中获取值。
+
+`borderaxespad`：浮点或`None`
+
+轴和图例边框之间的间距。 以字体大小为单位度量。 默认值为`None`，它将从`legend.borderaxespad` `rcParam`中获取值。
+
+`columnspacing`：浮点或`None`
+
+列间距。以字体大小为单位度量。 默认值为`None`，它将从`legend.columnspacing` `rcParam`中获取值。
+
+`handler_map`：字典或`None`
+
+自定义字典，用于将实例或类型映射到图例处理器。 这个`handler_map`会更新在`matplotlib.legend.Legend.get_legend_handler_map()`中获得的默认处理器字典。