Skip to content

Custom :rcparam: role. #10226

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 30, 2018
+231 −232
Merged

Custom :rcparam: role. #10226

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/*']
Expand Down
7 changes: 3 additions & 4 deletions doc/devel/MEP/MEP23.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**

Expand Down
3 changes: 2 additions & 1 deletion doc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
11 changes: 11 additions & 0 deletions doc/sphinxext/custom_roles.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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}
21 changes: 10 additions & 11 deletions lib/matplotlib/animation.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
107 changes: 52 additions & 55 deletions lib/matplotlib/axes/_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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*).
Expand Down Expand Up @@ -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 :

Expand Down
2 changes: 1 addition & 1 deletion lib/matplotlib/backends/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
-------
Expand Down
10 changes: 5 additions & 5 deletions lib/matplotlib/dates.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
Loading