diff --git a/doc/conf.py b/doc/conf.py index 45849d7538c2..58ed02415e00 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -35,7 +35,7 @@ 'sphinx.ext.inheritance_diagram', 'sphinx.ext.intersphinx', 'sphinx_gallery.gen_gallery', 'matplotlib.sphinxext.plot_directive', - 'sphinxext.github', + 'sphinxext.github', 'sphinxext.custom_roles', 'numpydoc'] exclude_patterns = ['api/api_changes/*', 'users/whats_new/*'] diff --git a/doc/devel/MEP/MEP23.rst b/doc/devel/MEP/MEP23.rst index f3785068a585..7001dfa527b7 100644 --- a/doc/devel/MEP/MEP23.rst +++ b/doc/devel/MEP/MEP23.rst @@ -37,10 +37,9 @@ Sometimes when there are too many figures open at the same time, it is desirable to be able to group these under the same window [see](https://github.com/matplotlib/matplotlib/issues/2194). -The proposed solution modifies `FigureManagerBase` to contain and -manage more than one `canvas`. The settings parameter -`rcParams['backend.multifigure']` control when the **MultiFigure** -behaviour is desired. +The proposed solution modifies `FigureManagerBase` to contain and manage more +than one `canvas`. The settings parameter :rc:`backend.multifigure` control +when the **MultiFigure** behaviour is desired. **Note** diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 5af9c6bf36d8..0938ac72371d 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -410,6 +410,8 @@ to keep in mind: ------- lines : `~matplotlib.collections.LineCollection` +* rcParams can be referenced with the custom ``:rc:`` role: + :literal:`:rc:\`foo\`` yields ``rcParams["foo"]``. Deprecated formatting conventions --------------------------------- @@ -417,7 +419,6 @@ Deprecated formatting conventions ``['solid' | 'dashed' | 'dotted']``. With numpydoc we have switched to their standard using curly braces ``{'solid', 'dashed', 'dotted'}``. - Linking to other code --------------------- To link to other methods, classes, or modules in Matplotlib you can encase diff --git a/doc/sphinxext/custom_roles.py b/doc/sphinxext/custom_roles.py new file mode 100644 index 000000000000..67492c0d5ac7 --- /dev/null +++ b/doc/sphinxext/custom_roles.py @@ -0,0 +1,11 @@ +from docutils import nodes + + +def rcparam_role(name, rawtext, text, lineno, inliner, options={}, content=[]): + rendered = nodes.Text('rcParams["{}"]'.format(text)) + return [nodes.literal(rawtext, rendered)], [] + + +def setup(app): + app.add_role("rc", rcparam_role) + return {"parallel_read_safe": True, "parallel_write_safe": True} diff --git a/lib/matplotlib/animation.py b/lib/matplotlib/animation.py index 56b0ae5315f9..f288e3892016 100644 --- a/lib/matplotlib/animation.py +++ b/lib/matplotlib/animation.py @@ -1051,32 +1051,31 @@ def save(self, filename, writer=None, fps=None, dpi=None, codec=None, writer : :class:`MovieWriter` or str, optional A `MovieWriter` instance to use or a key that identifies a class to use, such as 'ffmpeg'. If ``None``, defaults to - ``rcParams['animation.writer']``. + :rc:`animation.writer`. fps : number, optional Frames per second in the movie. Defaults to ``None``, which will use the animation's specified interval to set the frames per second. dpi : number, optional - Controls the dots per inch for the movie frames. This - combined with the figure's size in inches controls the size of - the movie. If ``None``, defaults to ``rcparam['savefig.dpi']``. + Controls the dots per inch for the movie frames. This combined with + the figure's size in inches controls the size of the movie. If + ``None``, defaults to :rc:`savefig.dpi`. codec : str, optional - The video codec to be used. Not all codecs are supported by - a given :class:`MovieWriter`. If ``None``, - default to ``rcParams['animation.codec']``. + The video codec to be used. Not all codecs are supported + by a given :class:`MovieWriter`. If ``None``, default to + :rc:`animation.codec`. bitrate : number, optional Specifies the number of bits used per second in the compressed movie, in kilobits per second. A higher number means a higher quality movie, but at the cost of increased file size. If ``None``, - defaults to ``rcParam['animation.bitrate']``. + defaults to :rc:`animation.bitrate`. extra_args : list, optional - List of extra string arguments to be passed to the - underlying movie utility. If ``None``, defaults to - ``rcParams['animation.extra_args']`` + List of extra string arguments to be passed to the underlying movie + utility. If ``None``, defaults to :rc:`animation.extra_args`. metadata : Dict[str, str], optional Dictionary of keys and values for metadata to include in diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index d61f6dfe809f..df2ccd55e278 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -411,27 +411,27 @@ def legend(self, *args, **kwargs): numpoints : None or int The number of marker points in the legend when creating a legend - entry for a line/:class:`matplotlib.lines.Line2D`. - Default is ``None`` which will take the value from the - ``legend.numpoints`` :data:`rcParam`. + 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 scatter plot/ - :class:`matplotlib.collections.PathCollection`. - Default is ``None`` which will take the value from the - ``legend.scatterpoints`` :data:`rcParam`. + 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 ``[0.375, 0.5, 0.3125]``. + 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 - the ``legend.markerscale`` :data:`rcParam `. + 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. @@ -440,42 +440,40 @@ def legend(self, *args, **kwargs): 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 the - ``legend.frameon`` :data:`rcParam`. + 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 the - ``legend.fancybox`` :data:`rcParam`. + 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 the - ``legend.shadow`` :data:`rcParam`. + 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 the - ``legend.framealpha`` :data:`rcParam`. - If shadow is activated and framealpha is ``None`` the - default value is being ignored. + 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 the - ``legend.facecolor`` :data:`rcParam`. - If ``"inherit"``, it will take the ``axes.facecolor`` - :data:`rcParam`. + 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 the - ``legend.edgecolor`` :data:`rcParam`. - If ``"inherit"``, it will take the ``axes.edgecolor`` - :data:`rcParam`. + 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 @@ -493,38 +491,38 @@ def legend(self, *args, **kwargs): 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 the - ``legend.borderpad`` :data:`rcParam`. + 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 the - ``legend.labelspacing`` :data:`rcParam`. + 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 the - ``legend.handlelength`` :data:`rcParam`. + 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 the - ``legend.handletextpad`` :data:`rcParam`. + 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 the - ``legend.borderaxespad`` :data:`rcParam`. + 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 the - ``legend.columnspacing`` :data:`rcParam`. + 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 @@ -2058,8 +2056,8 @@ def bar(self, *args, **kwargs): capsize : scalar, optional The length of the error bar caps in points. - Default: None, which will take the value from the - ``errorbar.capsize`` :data:`rcParam`. + Default: None, which will take the value from + :rc:`errorbar.capsize`. error_kw : dict, optional Dictionary of kwargs to be passed to the `~.Axes.errorbar` @@ -2376,8 +2374,8 @@ def barh(self, *args, **kwargs): capsize : scalar, optional The length of the error bar caps in points. - Default: None, which will take the value from the - ``errorbar.capsize`` :data:`rcParam`. + Default: None, which will take the value from + :rc:`errorbar.capsize`. error_kw : dict, optional Dictionary of kwargs to be passed to the `~.Axes.errorbar` @@ -2973,9 +2971,8 @@ def errorbar(self, x, y, yerr=None, xerr=None, the current style is used. capsize : scalar, optional, default: None - The length of the error bar caps in points. If None, it will - take the value from ``errorbar.capsize`` - :data:`rcParam`. + The length of the error bar caps in points. If None, it will take + the value from :rc:`errorbar.capsize`. capthick : scalar, optional, default: None An alias to the keyword argument *markeredgewidth* (a.k.a. *mew*). @@ -5609,9 +5606,9 @@ def pcolor(self, *args, **kwargs): ``edgecolors="none"`` is used. This eliminates artificial lines at patch boundaries, and works regardless of the value of alpha. If ``edgecolors`` is not "none", then the default ``antialiaseds`` - is taken from ``rcParams['patch.antialiased']``, which defaults to - True. Stroking the edges may be preferred if ``alpha`` is 1, but - will cause artifacts otherwise. + is taken from :rc:`patch.antialiased`, which defaults to True. + Stroking the edges may be preferred if ``alpha`` is 1, but will + cause artifacts otherwise. **kwargs : diff --git a/lib/matplotlib/backends/__init__.py b/lib/matplotlib/backends/__init__.py index f74eabb95cbc..bc07522797ab 100644 --- a/lib/matplotlib/backends/__init__.py +++ b/lib/matplotlib/backends/__init__.py @@ -28,7 +28,7 @@ def pylab_setup(name=None): ---------- name : str, optional The name of the backend to use. If `None`, falls back to - ``matplotlib.get_backend()`` (which return ``rcParams['backend']``) + ``matplotlib.get_backend()`` (which return :rc:`backend`). Returns ------- diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py index 3eab32648893..09bae4ea5b37 100644 --- a/lib/matplotlib/dates.py +++ b/lib/matplotlib/dates.py @@ -296,12 +296,12 @@ def _dt64_to_ordinalf(d): def _from_ordinalf(x, tz=None): """ Convert Gregorian float of the date, preserving hours, minutes, - seconds and microseconds. Return value is a :class:`datetime`. + seconds and microseconds. Return value is a `~.datetime`. - The input date `x` is a float in ordinal days at UTC, and the output will - be the specified :class:`datetime` object corresponding to that time in - timezone `tz`, or if `tz` is `None`, in the timezone specified in - `rcParams['timezone']`. + The input date *x* is a float in ordinal days at UTC, and the output will + be the specified `~.datetime` object corresponding to that time in + timezone *tz*, or if *tz* is ``None``, in the timezone specified in + :rc:`timezone`. """ if tz is None: tz = _get_rc_timezone() diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 216353a0c71a..1716f8dee208 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1447,27 +1447,27 @@ def legend(self, *args, **kwargs): numpoints : None or int The number of marker points in the legend when creating a legend - entry for a line/:class:`matplotlib.lines.Line2D`. - Default is ``None`` which will take the value from the - ``legend.numpoints`` :data:`rcParam`. + 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 scatter plot/ - :class:`matplotlib.collections.PathCollection`. - Default is ``None`` which will take the value from the - ``legend.scatterpoints`` :data:`rcParam`. + 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 ``[0.375, 0.5, 0.3125]``. + 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 - the ``legend.markerscale`` :data:`rcParam `. + 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. @@ -1476,42 +1476,40 @@ def legend(self, *args, **kwargs): 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 the - ``legend.frameon`` :data:`rcParam`. + 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 the - ``legend.fancybox`` :data:`rcParam`. + 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 the - ``legend.shadow`` :data:`rcParam`. + 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 the - ``legend.framealpha`` :data:`rcParam`. - If shadow is activated and framealpha is ``None`` the - default value is being ignored. + 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 the - ``legend.facecolor`` :data:`rcParam`. - If ``"inherit"``, it will take the ``axes.facecolor`` - :data:`rcParam`. + 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 the - ``legend.edgecolor`` :data:`rcParam`. - If ``"inherit"``, it will take the ``axes.edgecolor`` - :data:`rcParam`. + 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 @@ -1529,38 +1527,38 @@ def legend(self, *args, **kwargs): 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 the - ``legend.borderpad`` :data:`rcParam`. + 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 the - ``legend.labelspacing`` :data:`rcParam`. + 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 the - ``legend.handlelength`` :data:`rcParam`. + 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 the - ``legend.handletextpad`` :data:`rcParam`. + 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 the - ``legend.borderaxespad`` :data:`rcParam`. + 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 the - ``legend.columnspacing`` :data:`rcParam`. + 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 diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py index da1a342b59fa..08b5c45de1cf 100644 --- a/lib/matplotlib/legend.py +++ b/lib/matplotlib/legend.py @@ -134,15 +134,14 @@ def _update_bbox_to_anchor(self, loc_in_canvas): corner of the legend in axes coordinates (in which case ``bbox_to_anchor`` will be ignored). -bbox_to_anchor : :class:`matplotlib.transforms.BboxBase` instance \ -or tuple of floats +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) + loc='upper right', bbox_to_anchor=(0.5, 0.5) ncol : integer The number of columns that the legend has. Default is 1. @@ -160,27 +159,27 @@ def _update_bbox_to_anchor(self, loc_in_canvas): numpoints : None or int The number of marker points in the legend when creating a legend - entry for a line/:class:`matplotlib.lines.Line2D`. - Default is ``None`` which will take the value from the - ``legend.numpoints`` :data:`rcParam`. + 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 scatter plot/ - :class:`matplotlib.collections.PathCollection`. - Default is ``None`` which will take the value from the - ``legend.scatterpoints`` :data:`rcParam`. + 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 ``[0.375, 0.5, 0.3125]``. + 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 - the ``legend.markerscale`` :data:`rcParam `. + 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. @@ -189,42 +188,40 @@ def _update_bbox_to_anchor(self, loc_in_canvas): 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 the - ``legend.frameon`` :data:`rcParam`. + 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 the - ``legend.fancybox`` :data:`rcParam`. + 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 the - ``legend.shadow`` :data:`rcParam`. + 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 the - ``legend.framealpha`` :data:`rcParam`. - If shadow is activated and framealpha is ``None`` the - default value is being ignored. + 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 the - ``legend.facecolor`` :data:`rcParam`. - If ``"inherit"``, it will take the ``axes.facecolor`` - :data:`rcParam`. + 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 the - ``legend.edgecolor`` :data:`rcParam`. - If ``"inherit"``, it will take the ``axes.edgecolor`` - :data:`rcParam`. + 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 @@ -242,38 +239,38 @@ def _update_bbox_to_anchor(self, loc_in_canvas): 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 the - ``legend.borderpad`` :data:`rcParam`. + 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 the - ``legend.labelspacing`` :data:`rcParam`. + 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 the - ``legend.handlelength`` :data:`rcParam`. + 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 the - ``legend.handletextpad`` :data:`rcParam`. + 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 the - ``legend.borderaxespad`` :data:`rcParam`. + 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 the - ``legend.columnspacing`` :data:`rcParam`. + 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 @@ -417,27 +414,27 @@ def __init__(self, parent, handles, labels, numpoints : None or int The number of marker points in the legend when creating a legend - entry for a line/:class:`matplotlib.lines.Line2D`. - Default is ``None`` which will take the value from the - ``legend.numpoints`` :data:`rcParam`. + 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 scatter plot/ - :class:`matplotlib.collections.PathCollection`. - Default is ``None`` which will take the value from the - ``legend.scatterpoints`` :data:`rcParam`. + 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 ``[0.375, 0.5, 0.3125]``. + 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 - the ``legend.markerscale`` :data:`rcParam `. + 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. @@ -446,42 +443,40 @@ def __init__(self, parent, handles, labels, 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 the - ``legend.frameon`` :data:`rcParam`. + 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 the - ``legend.fancybox`` :data:`rcParam`. + 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 the - ``legend.shadow`` :data:`rcParam`. + 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 the - ``legend.framealpha`` :data:`rcParam`. - If shadow is activated and framealpha is ``None`` the - default value is being ignored. + 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 the - ``legend.facecolor`` :data:`rcParam`. - If ``"inherit"``, it will take the ``axes.facecolor`` - :data:`rcParam`. + 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 the - ``legend.edgecolor`` :data:`rcParam`. - If ``"inherit"``, it will take the ``axes.edgecolor`` - :data:`rcParam`. + 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 @@ -499,38 +494,38 @@ def __init__(self, parent, handles, labels, 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 the - ``legend.borderpad`` :data:`rcParam`. + 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 the - ``legend.labelspacing`` :data:`rcParam`. + 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 the - ``legend.handlelength`` :data:`rcParam`. + 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 the - ``legend.handletextpad`` :data:`rcParam`. + 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 the - ``legend.borderaxespad`` :data:`rcParam`. + 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 the - ``legend.columnspacing`` :data:`rcParam`. + 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 diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py index bdaeda515340..7477916828fa 100644 --- a/lib/matplotlib/text.py +++ b/lib/matplotlib/text.py @@ -1211,8 +1211,8 @@ def set_usetex(self, usetex): Parameters ---------- usetex : bool or None - Whether to render using TeX, ``None`` means to use the - ``rcParams['text.usetex']``. + Whether to render using TeX, ``None`` means to use + :rc:`text.usetex`. .. ACCEPTS: bool or None """ @@ -1224,10 +1224,10 @@ def set_usetex(self, usetex): def get_usetex(self): """ - Return whether this `Text` object will render using TeX. + Return whether this `Text` object uses TeX for rendering. - If the user has not manually set this value, it will default to - the value of `rcParams['text.usetex']` + If the user has not manually set this value, it defaults to + :rc:`text.usetex`. """ if self._usetex is None: return rcParams['text.usetex'] diff --git a/lib/matplotlib/ticker.py b/lib/matplotlib/ticker.py index 812f39338603..50df08a12307 100644 --- a/lib/matplotlib/ticker.py +++ b/lib/matplotlib/ticker.py @@ -1388,9 +1388,9 @@ def symbol(self): """ The configured percent symbol as a string. - If LaTeX is enabled via ``rcParams['text.usetex']``, the special - characters `{'#', '$', '%', '&', '~', '_', '^', '\\', '{', '}'}` - are automatically escaped in the string. + If LaTeX is enabled via :rc:`text.usetex`, the special characters + ``{'#', '$', '%', '&', '~', '_', '^', '\\', '{', '}'}`` are + automatically escaped in the string. """ symbol = self._symbol if not symbol: @@ -1819,14 +1819,13 @@ def __init__(self, *args, **kwargs): *prune* ['lower' | 'upper' | 'both' | None] - Remove edge ticks -- useful for stacked or ganged plots - where the upper tick of one axes overlaps with the lower - tick of the axes above it, primarily when - `rcParams['axes.autolimit_mode']` is `'round_numbers'`. - If `prune=='lower'`, the smallest tick will - be removed. If `prune=='upper'`, the largest tick will be - removed. If `prune=='both'`, the largest and smallest ticks - will be removed. If `prune==None`, no ticks will be removed. + Remove edge ticks -- useful for stacked or ganged plots where + the upper tick of one axes overlaps with the lower tick of the + axes above it, primarily when :rc:`axes.autolimit_mode` is + ``'round_numbers'``. If ``prune=='lower'``, the smallest tick will + be removed. If ``prune == 'upper'``, the largest tick will be + removed. If ``prune == 'both'``, the largest and smallest ticks + will be removed. If ``prune == None``, no ticks will be removed. *min_n_ticks* Relax `nbins` and `integer` constraints if necessary to