Modernize stem3d documentation.

Author: QuLogic

examples/mplot3d/stem3d_demo.py

@@ -1,13 +1,36 @@
-from mpl_toolkits.mplot3d import Axes3D
+"""
+=======
+3D stem
+=======
+
+Demonstration of a stem plot in 3D, which plots vertical lines from a baseline
+to the *z*-coordinate and places a marker at the tip.
+"""
+
 import matplotlib.pyplot as plt
 import numpy as np
 
-fig = plt.figure()
-ax = fig.gca(projection='3d')
 theta = np.linspace(0, 2*np.pi)
 x = np.cos(theta)
 y = np.sin(theta)
 z = theta
-markerline, stemlines, baseline = ax.stem(x, y, z)
+
+fig, ax = plt.subplots(subplot_kw=dict(projection='3d'))
+ax.stem(x, y, z)
+
+plt.show()
+
+#############################################################################
+#
+# The position of the baseline can be adapted using *bottom*. The parameters
+# *linefmt*, *markerfmt*, and *basefmt* control basic format properties of the
+# plot. However, in contrast to `~.axes3d.Axes3D.plot` not all properties are
+# configurable via keyword arguments. For more advanced control adapt the line
+# objects returned by `~.stem3D`.
+
+fig, ax = plt.subplots(subplot_kw=dict(projection='3d'))
+markerline, stemlines, baseline = ax.stem(
+    x, y, z, linefmt='grey', markerfmt='D', bottom=np.pi)
+markerline.set_markerfacecolor('none')
 
 plt.show()

examples/mplot3d/stem3d_demo2.py

@@ -3293,26 +3293,61 @@ def stem(self, x, y, z, *, linefmt='C0-', markerfmt='C0o', basefmt='C3-',
         """
         Create a 3D stem plot.
 
-        By default, stem plots vertical lines (using *linefmt*) in the z
-        direction at each *x* and *y* location from the baseline to *z*, and
-        places a marker there using *markerfmt*. By default, the baseline at
-        the xy-plane is plotted using *basefmt*.
+        A stem plot draws lines perpendicular to a baseline, and places markers
+        at the heads. By default, the baseline is defined by *x* and *y*, and
+        stems are drawn vertically from *bottom* to *z*.
 
-        *x*, *y, and *z* values are required and must be arrays of the same
-        length.
-
-        If no zdir value is provided, then it is set to default and no rotation
-        occurs.
+        Parameters
+        ----------
+        x, y, z : array-like
+            The positions of the heads of the stems. The baseline is defined by
+            two of these positions and *bottom*, and stems are drawn from
+            *bottom* to the third position. By default, the *x* and *y*
+            positions are used for the baseline and *z* for the head position,
+            but this can be changed by *zdir*.
+
+        linefmt : str, default: 'C0-'
+            A string defining the properties of the vertical lines. Usually,
+            this will be a color or a color and a linestyle:
+
+            =========  =============
+            Character  Line Style
+            =========  =============
+            ``'-'``    solid line
+            ``'--'``   dashed line
+            ``'-.'``   dash-dot line
+            ``':'``    dotted line
+            =========  =============
+
+            Note: While it is technically possible to specify valid formats
+            other than color or color and linestyle (e.g. 'rx' or '-.'), this
+            is beyond the intention of the method and will most likely not
+            result in a reasonable plot.
+
+        markerfmt : str, default: 'C0o'
+            A string defining the properties of the markers at the stem heads.
+
+        basefmt : str, default: 'C3-'
+            A format string defining the properties of the baseline.
+
+        bottom : float, default: 0
+            The x/y/z-position of the baseline (depending on *zdir*).
+
+        label : str, default: None
+            The label to use for the stems in legends.
 
-        Return value is a tuple (*markerline*, *stemlines*, *baseline*).
+        zdir : {'x', 'y', 'z'}, default: 'z'
+            The direction along which stems are drawn.
 
-        .. seealso::
-            This `document
-            <http://www.mathworks.com/help/techdoc/ref/stem3.html>`_ for
-            details.
+        Returns
+        -------
+        `.StemContainer`
+            The container may be treated like a tuple
+            (*markerline*, *stemlines*, *baseline*)
 
-        **Example:**
-        .. plot:: /mplot3d/stem3d_demo.py
+        Examples
+        --------
+        .. plot:: gallery/mplot3d/stem3d_demo.py
         """
 
         from matplotlib.container import StemContainer