DOC: Add documentation for lightsource parameter

eric-wieser · eric-wieser · commit 9e73e2591ad9 · 2018-07-13T16:26:42.000+01:00
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -1593,7 +1593,11 @@ def plot_surface(self, X, Y, Z, *args, norm=None, vmin=None,
             Bounds for the normalization.
 
         shade : bool
-            Whether to shade the face colors.
+            Whether to shade the facecolors. Defaults to True. Shading is
+            always disabled when `cmap` is specified.
+
+        lightsource : LightSource
+            The lightsource to use when `shade` is True.
 
         **kwargs :
             Other arguments are forwarded to `.Poly3DCollection`.
@@ -1882,17 +1886,24 @@ def plot_wireframe(self, X, Y, Z, *args, **kwargs):
     def plot_trisurf(self, *args, color=None, norm=None, vmin=None, vmax=None,
                      lightsource=None, **kwargs):
         """
-        ============= ================================================
-        Argument      Description
-        ============= ================================================
-        *X*, *Y*, *Z* Data values as 1D arrays
-        *color*       Color of the surface patches
-        *cmap*        A colormap for the surface patches.
-        *norm*        An instance of Normalize to map values to colors
-        *vmin*        Minimum value to map
-        *vmax*        Maximum value to map
-        *shade*       Whether to shade the facecolors
-        ============= ================================================
+
+        Parameters
+        ----------
+        X, Y, Z : array-like
+            Data values as 1D arrays
+        color
+            Color of the surface patches
+        cmap
+            A colormap for the surface patches.
+        norm : Normalize
+            An instance of Normalize to map values to colors.
+        vmin, vmax : scalar, optional, default: None
+            Minimum and maximum value to map.
+        shade : bool
+            Whether to shade the facecolors. Defaults to True. Shading is
+            always disabled when `cmap` is specified.
+        lightsource : LightSource
+            The lightsource to use when `shade` is True.
 
         The (optional) triangulation can be specified in one of two ways;
         either::
@@ -1920,7 +1931,8 @@ def plot_trisurf(self, *args, color=None, norm=None, vmin=None, vmax=None,
         Other arguments are passed on to
         :class:`~mpl_toolkits.mplot3d.art3d.Poly3DCollection`
 
-        **Examples:**
+        Examples
+        --------
 
         .. plot:: gallery/mplot3d/trisurf3d.py
         .. plot:: gallery/mplot3d/trisurf3d_2.py
