diff --git a/galleries/examples/lines_bars_and_markers/linestyles.py b/galleries/examples/lines_bars_and_markers/linestyles.py index 25b053e912bd..203484012164 100644 --- a/galleries/examples/lines_bars_and_markers/linestyles.py +++ b/galleries/examples/lines_bars_and_markers/linestyles.py @@ -1,15 +1,23 @@ """ +.. _linestyle_def: + ========== Linestyles ========== -Simple linestyles can be defined using the strings "solid", "dotted", "dashed" -or "dashdot". More refined control can be achieved by providing a dash tuple -``(offset, (on_off_seq))``. For example, ``(0, (3, 10, 1, 15))`` means -(3pt line, 10pt space, 1pt line, 15pt space) with no offset, while -``(5, (10, 3))``, means (10pt line, 3pt space), but skip the first 5pt line. -See also `.Line2D.set_linestyle`. The specific on/off sequences of the -"dotted", "dashed" and "dashdot" styles are configurable: +Linestyles can be specified in two ways: + +* **Named linestyles**: "solid", "dotted", "dashed", "dashdot" and their + short forms "-", ":", "--", "-." +* **Parametrized linestyles**: a dash tuple ``(offset, (on_off_seq))``. For example, + ``(0, (3, 10, 1, 15))`` means (3pt line, 10pt space, 1pt line, 15pt space) with no + offset, while ``(5, (10, 3))``, means (10pt line, 3pt space), but skip the first + 5pt line. + +See also `.Line2D.set_linestyle`. + +The specific on/off sequences of the "dotted", "dashed" and "dashdot" styles are +configurable: * :rc:`lines.dotted_pattern` * :rc:`lines.dashed_pattern` diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index cfc21a1a7cf5..09aef856dc48 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -1998,7 +1998,7 @@ def acorr(self, x, **kwargs): Other Parameters ---------------- - linestyle : `~matplotlib.lines.Line2D` property, optional + linestyle : :mpltype:`linestyle`, optional The linestyle for plotting the data points. Only used if *usevlines* is ``False``. @@ -2078,7 +2078,7 @@ def xcorr(self, x, y, normed=True, detrend=mlab.detrend_none, Other Parameters ---------------- - linestyle : `~matplotlib.lines.Line2D` property, optional + linestyle : :mpltype:`linestyle`, optional The linestyle for plotting the data points. Only used if *usevlines* is ``False``. @@ -4027,11 +4027,8 @@ def errorbar(self, x, y, yerr=None, xerr=None, The linewidth of the errorbar lines. If None, the linewidth of the current style is used. - elinestyle : str or tuple, default: 'solid' + elinestyle : :mpltype:`linestyle`, default: 'solid' The linestyle of the errorbar lines. - Valid values for linestyles include {'-', '--', '-.', - ':', '', (offset, on-off-seq)}. See `.Line2D.set_linestyle` for a - complete description. capsize : float, default: :rc:`errorbar.capsize` The length of the error bar caps in points. diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index c972c3febb6e..653b353ac9c0 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -3608,8 +3608,8 @@ def tick_params(self, axis='both', **kwargs): Transparency of gridlines: 0 (transparent) to 1 (opaque). grid_linewidth : float Width of gridlines in points. - grid_linestyle : str - Any valid `.Line2D` line style spec. + grid_linestyle : :mpltype:`linestyle` + Linestyle of the gridlines. Examples -------- diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py index 95150115fc56..703a77ee593a 100644 --- a/lib/matplotlib/collections.py +++ b/lib/matplotlib/collections.py @@ -675,7 +675,7 @@ def set_linestyle(self, ls): Parameters ---------- - ls : {'-', '--', '-.', ':', '', ...} or (offset, on-off-seq) or list thereof + ls : :mpltype:`linestyle` or list of :mpltype:`linestyle` If a list, the individual elements are assigned to the elements of the collection. @@ -1933,14 +1933,8 @@ def __init__(self, The line width of the event lines, in points. color : :mpltype:`color` or list of :mpltype:`color`, default: :rc:`lines.color` The color of the event lines. - linestyle : str or tuple or list thereof, default: 'solid' - Valid strings are ['solid', 'dashed', 'dashdot', 'dotted', - '-', '--', '-.', ':']. Dash tuples should be of the form:: - - (offset, onoffseq), - - where *onoffseq* is an even length tuple of on and off ink - in points. + linestyle : :mpltype:`linestyle`, default: 'solid' + The linestyle of the event lines. antialiased : bool or list thereof, default: :rc:`lines.antialiased` Whether to use antialiasing for drawing the lines. **kwargs diff --git a/lib/matplotlib/inset.py b/lib/matplotlib/inset.py index aae640db6f81..f266a048e5cc 100644 --- a/lib/matplotlib/inset.py +++ b/lib/matplotlib/inset.py @@ -128,38 +128,11 @@ def set_linestyle(self, ls): Parameters ---------- - ls : {'-', '--', '-.', ':', '', ...} or (offset, on-off-seq) - Possible values: + ls : :mpltype:`linestyle` + A named line style (e.g. "dashed", or short "--") or a dash tuple + ``(offset, (on_off_seq))``. - - A string: - - ======================================================= ================ - linestyle description - ======================================================= ================ - ``'-'`` or ``'solid'`` solid line - ``'--'`` or ``'dashed'`` dashed line - ``'-.'`` or ``'dashdot'`` dash-dotted line - ``':'`` or ``'dotted'`` dotted line - ``''`` or ``'none'`` (discouraged: ``'None'``, ``' '``) draw nothing - ======================================================= ================ - - - A tuple describing the start position and lengths of dashes and spaces: - - (offset, onoffseq) - - where - - - *offset* is a float specifying the offset (in points); i.e. how much - is the dash pattern shifted. - - *onoffseq* is a sequence of on and off ink in points. There can be - arbitrary many pairs of on and off values. - - Example: The tuple ``(0, (10, 5, 1, 5))`` means that the pattern starts - at the beginning of the line. It draws a 10 point long dash, - then a 5 point long space, then a 1 point long dash, followed by a 5 point - long space, and then the pattern repeats. - - For examples see :doc:`/gallery/lines_bars_and_markers/linestyles`. + For a full reference see :doc:`/gallery/lines_bars_and_markers/linestyles`. """ self._shared_setter('linestyle', ls) diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py index f43494843607..9c93d9491bdd 100644 --- a/lib/matplotlib/lines.py +++ b/lib/matplotlib/lines.py @@ -1165,7 +1165,7 @@ def set_linestyle(self, ls): Parameters ---------- - ls : {'-', '--', '-.', ':', '', ...} or (offset, on-off-seq) + ls : :mpltype:`linestyle` Possible values: - A string: diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py index 711927b556ca..922bd932f605 100644 --- a/lib/matplotlib/patches.py +++ b/lib/matplotlib/patches.py @@ -510,38 +510,11 @@ def set_linestyle(self, ls): Parameters ---------- - ls : {'-', '--', '-.', ':', '', ...} or (offset, on-off-seq) - Possible values: + ls : :mpltype:`linestyle` + A named line style (e.g. "dashed", or short "--") or a dash tuple + ``(offset, (on_off_seq))``. - - A string: - - ======================================================= ================ - linestyle description - ======================================================= ================ - ``'-'`` or ``'solid'`` solid line - ``'--'`` or ``'dashed'`` dashed line - ``'-.'`` or ``'dashdot'`` dash-dotted line - ``':'`` or ``'dotted'`` dotted line - ``''`` or ``'none'`` (discouraged: ``'None'``, ``' '``) draw nothing - ======================================================= ================ - - - A tuple describing the start position and lengths of dashes and spaces: - - (offset, onoffseq) - - where - - - *offset* is a float specifying the offset (in points); i.e. how much - is the dash pattern shifted. - - *onoffseq* is a sequence of on and off ink in points. There can be - arbitrary many pairs of on and off values. - - Example: The tuple ``(0, (10, 5, 1, 5))`` means that the pattern starts - at the beginning of the line. It draws a 10 point long dash, - then a 5 point long space, then a 1 point long dash, followed by a 5 point - long space, and then the pattern repeats. - - For examples see :doc:`/gallery/lines_bars_and_markers/linestyles`. + For a full reference see :doc:`/gallery/lines_bars_and_markers/linestyles`. """ if ls is None: ls = "solid" diff --git a/lib/matplotlib/sphinxext/roles.py b/lib/matplotlib/sphinxext/roles.py index 0b696f830543..2c1d3e97d82f 100644 --- a/lib/matplotlib/sphinxext/roles.py +++ b/lib/matplotlib/sphinxext/roles.py @@ -143,6 +143,7 @@ def _mpltype_role(name, rawtext, text, lineno, inliner, options=None, content=No type_to_link_target = { 'color': 'colors_def', 'hatch': 'hatch_def', + 'linestyle': 'linestyle_def', } if mpltype not in type_to_link_target: raise ValueError(f"Unknown mpltype: {mpltype!r}")