Improve docstring of Axes.spy

timhoffm · timhoffm · commit 71c597e0a6d4 · 2018-06-02T01:08:27.000+02:00
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -5044,7 +5044,7 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
               that the data fit in the axes. In general, this will result in
               non-square pixels.
 
-            Defaults to :rc:`image.aspect`.
+            If not given, use :rc:`image.aspect` (default: 'equal').
 
         interpolation : str, optional
             The interpolation method used. If *None*
@@ -7293,61 +7293,82 @@ def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
     def spy(self, Z, precision=0, marker=None, markersize=None,
             aspect='equal', origin="upper", **kwargs):
         """
-        Plot the sparsity pattern on a 2-D array.
+        Plot the sparsity pattern of a 2D array.
 
-        ``spy(Z)`` plots the sparsity pattern of the 2-D array *Z*.
+        This visualizes the non-zero values of the array.
+
+        Two plotting styles are available: image and marker. Both
+        are available for full arrays, but only the marker style
+        works for `scipy.sparse.spmatrix` instances.
+
+        **Image style**
+
+        If *marker* and *markersize* are *None*, `~.Axes.imshow` is used. Any
+        extra remaining kwargs are passed to this method.
+
+        **Marker style**
+
+        If *Z* is a `scipy.sparse.spmatrix` or *marker* or *markersize* are
+        *None*, a `~matplotlib.lines.Line2D` object will be returned with
+        the value of marker determining the marker type, and any
+        remaining kwargs passed to `~.Axes.plot`.
 
         Parameters
         ----------
-
-        Z : sparse array (n, m)
+        Z : array-like (M, N)
             The array to be plotted.
 
-        precision : float, optional, default: 0
-            If *precision* is 0, any non-zero value will be plotted; else,
+        precision : float or 'present', optional, default: 0
+            If *precision* is 0, any non-zero value will be plotted. Otherwise,
             values of :math:`|Z| > precision` will be plotted.
 
-            For :class:`scipy.sparse.spmatrix` instances, there is a special
-            case: if *precision* is 'present', any value present in the array
+            For :class:`scipy.sparse.spmatrix` instances, you can also
+            pass 'present'. In this case any value present in the array
             will be plotted, even if it is identically zero.
 
-        origin : ["upper", "lower"], optional, default: "upper"
+        origin : {'upper', 'lower'}, optional
             Place the [0,0] index of the array in the upper left or lower left
-            corner of the axes.
+            corner of the axes. The convention 'upper' is typically used for
+            matrices and images.
+            If not given, :rc:`image.origin` is used, defaulting to 'upper'.
 
-        aspect : ['auto' | 'equal' | scalar], optional, default: "equal"
 
-            If 'equal', and `extent` is None, changes the axes aspect ratio to
-            match that of the image. If `extent` is not `None`, the axes
-            aspect ratio is changed to match that of the extent.
+        aspect : {'equal', 'auto', None} or float, optional
+            Controls the aspect ratio of the axes. The aspect is of particular
+            relevance for images since it may distort the image, i.e. pixel
+            will not be square.
 
+            This parameter is a shortcut for explicitly calling
+            `.Axes.set_aspect`. See there for further details.
 
-            If 'auto', changes the image aspect ratio to match that of the
-            axes.
+            - 'equal': Ensures an aspect ratio of 1. Pixels will be square
+              (unless pixel sizes are explicitly made non-square in data
+              coordinates using *extent*).
+            - 'auto': The axes is kept fixed and the aspect is adjusted so
+              that the data fit in the axes. In general, this will result in
+              non-square pixels.
+            - *None*: Use :rc:`image.aspect` (default: 'equal').
 
-            If None, default to rc ``image.aspect`` value.
+            Default: 'equal'
 
-        Two plotting styles are available: image or marker. Both
-        are available for full arrays, but only the marker style
-        works for :class:`scipy.sparse.spmatrix` instances.
+        Returns
+        -------
+        ret : `~matplotlib.image.AxesImage` or `.Line2D`
+            The return type depends on the plotting style (see above).
 
-        If *marker* and *markersize* are *None*, an image will be
-        returned and any remaining kwargs are passed to
-        :func:`~matplotlib.pyplot.imshow`; else, a
-        :class:`~matplotlib.lines.Line2D` object will be returned with
-        the value of marker determining the marker type, and any
-        remaining kwargs passed to the
-        :meth:`~matplotlib.axes.Axes.plot` method.
+        Additional Parameters
+        ---------------------
+        **kwargs
+            The supported additional parameters depend on the plotting style.
 
-        If *marker* and *markersize* are *None*, useful kwargs include:
+            For the image style, you can pass any parameters supported by
+            `~.Axes.imshow`. Commonly used parameters include *cmap* and
+            *alpha*.
 
-        * *cmap*
-        * *alpha*
+            For the marker style, you can pass any parameters
+            supported by `~.Axes.plot. Commonly used parameters include
+            *color*, *marker* and *markersize*.
 
-        See also
-        --------
-        imshow : for image options.
-        plot : for plotting options
         """
         if marker is None and markersize is None and hasattr(Z, 'tocoo'):
             marker = 's'
