Backport PR #15372: Add example for drawstyle

jklymak · MeeseeksDev[bot] · commit ca179a64c843 · 2019-10-23T02:35:13.000Z
diff --git a/examples/lines_bars_and_markers/step_demo.py b/examples/lines_bars_and_markers/step_demo.py
@@ -18,15 +18,35 @@
 y = np.sin(x / 2)
 
 plt.step(x, y + 2, label='pre (default)')
-plt.plot(x, y + 2, 'C0o', alpha=0.5)
+plt.plot(x, y + 2, 'o--', color='grey', alpha=0.3)
 
 plt.step(x, y + 1, where='mid', label='mid')
-plt.plot(x, y + 1, 'C1o', alpha=0.5)
+plt.plot(x, y + 1, 'o--', color='grey', alpha=0.3)
 
 plt.step(x, y, where='post', label='post')
-plt.plot(x, y, 'C2o', alpha=0.5)
+plt.plot(x, y, 'o--', color='grey', alpha=0.3)
 
+plt.grid(axis='x', color='0.95')
 plt.legend(title='Parameter where:')
+plt.title('plt.step(where=...)')
+plt.show()
+
+#############################################################################
+# The same behavior can be achieved by using the ``drawstyle`` parameter of
+# `.pyplot.plot`.
+
+plt.plot(x, y + 2, drawstyle='steps', label='steps (=steps-pre)')
+plt.plot(x, y + 2, 'o--', color='grey', alpha=0.3)
+
+plt.plot(x, y + 1, drawstyle='steps-mid', label='steps-mid')
+plt.plot(x, y + 1, 'o--', color='grey', alpha=0.3)
+
+plt.plot(x, y, drawstyle='steps-post', label='steps-post')
+plt.plot(x, y, 'o--', color='grey', alpha=0.3)
+
+plt.grid(axis='x', color='0.95')
+plt.legend(title='Parameter drawstyle:')
+plt.title('plt.plot(drawstyle=...)')
 plt.show()
 
 #############################################################################
@@ -42,3 +62,5 @@
 import matplotlib
 matplotlib.axes.Axes.step
 matplotlib.pyplot.step
+matplotlib.axes.Axes.plot
+matplotlib.pyplot.plot
diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py
@@ -574,6 +574,9 @@ def set_markevery(self, every):
               be 0.5 multiplied by the display-coordinate-diagonal-distance
               along the line.
 
+            For examples see
+            :doc:`/gallery/lines_bars_and_markers/markevery_demo`.
+
         Notes
         -----
         Setting the markevery property will only show markers at actual data
@@ -1079,6 +1082,7 @@ def set_drawstyle(self, drawstyle):
             - 'steps' is equal to 'steps-pre' and is maintained for
               backward-compatibility.
 
+            For examples see :doc:`/gallery/lines_bars_and_markers/step_demo`.
         """
         if drawstyle is None:
             drawstyle = 'default'
@@ -1171,6 +1175,8 @@ def set_linestyle(self, ls):
 
               where ``onoffseq`` is an even length tuple of on and off ink
               in points. See also :meth:`set_dashes`.
+
+            For examples see :doc:`/gallery/lines_bars_and_markers/linestyles`.
         """
         if isinstance(ls, str):
             ds, ls = self._split_drawstyle_linestyle(ls)
@@ -1325,7 +1331,7 @@ def set_dashes(self, seq):
             self.set_linestyle((0, seq))
 
     def update_from(self, other):
-        """Copy properties from other to self."""
+        """Copy properties from *other* to self."""
         Artist.update_from(self, other)
         self._linestyle = other._linestyle
         self._linewidth = other._linewidth
@@ -1402,6 +1408,7 @@ def set_dash_capstyle(self, s):
         Parameters
         ----------
         s : {'butt', 'round', 'projecting'}
+            For examples see :doc:`/gallery/lines_bars_and_markers/joinstyle`.
         """
         s = s.lower()
         cbook._check_in_list(self.validCap, s=s)
@@ -1416,6 +1423,7 @@ def set_solid_capstyle(self, s):
         Parameters
         ----------
         s : {'butt', 'round', 'projecting'}
+            For examples see :doc:`/gallery/lines_bars_and_markers/joinstyle`.
         """
         s = s.lower()
         cbook._check_in_list(self.validCap, s=s)
