Custom :rcparam: role.

anntzer · anntzer · commit 0c9fddf887a9 · 2018-01-29T15:04:42.000-08:00
diff --git 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
@@ -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
@@ -410,14 +410,15 @@ 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
 ---------------------------------
 * Formerly, we have used square brackets for explicit parameter lists
   ``['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
@@ -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
@@ -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
@@ -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<matplotlib.rcParams>`.
+            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<matplotlib.rcParams>`.
+            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 <matplotlib.rcParams>`.
+            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<matplotlib.rcParams>`.
+            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<matplotlib.rcParams>`.
+            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<matplotlib.rcParams>`.
+            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<matplotlib.rcParams>`.
-            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<matplotlib.rcParams>`.
-            If ``"inherit"``, it will take the ``axes.facecolor``
-            :data:`rcParam<matplotlib.rcParams>`.
+            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<matplotlib.rcParams>`.
-            If ``"inherit"``, it will take the ``axes.edgecolor``
-            :data:`rcParam<matplotlib.rcParams>`.
+            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<matplotlib.rcParams>`.
+            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<matplotlib.rcParams>`.
+            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<matplotlib.rcParams>`.
+            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<matplotlib.rcParams>`.
+            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<matplotlib.rcParams>`.
+            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<matplotlib.rcParams>`.
+            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<matplotlib.rcParams>`.
+           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<matplotlib.rcParams>`.
+           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<matplotlib.rcParams>`.
+            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
@@ -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
@@ -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
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
diff --git a/lib/matplotlib/ticker.py b/lib/matplotlib/ticker.py
