Silence some Sphinx warnings by rewriting docstrings.

lib/matplotlib/axes/_axes.py

@@ -124,9 +124,10 @@ def set_title(self, label, fontdict=None, loc="center", **kwargs):
 
         Other parameters
         ----------------
-        Other keyword arguments are text properties, see
-        :class:`~matplotlib.text.Text` for a list of valid text
-        properties.
+        kwargs : text properties
+            Other keyword arguments are text properties, see
+            :class:`~matplotlib.text.Text` for a list of valid text
+            properties.
         """
         try:
             title = {'left': self._left_title,
@@ -3021,10 +3022,11 @@ def boxplot(self, x, notch=False, sym='b+', vert=True, whis=1.5,
         Returns
         -------
 
-        A dictionary mapping each component of the boxplot
-        to a list of the :class:`matplotlib.lines.Line2D`
-        instances created. That dictionary has the following keys
-        (assuming vertical boxplots):
+        result : dict
+            A dictionary mapping each component of the boxplot
+            to a list of the :class:`matplotlib.lines.Line2D`
+            instances created. That dictionary has the following keys
+            (assuming vertical boxplots):
 
             - boxes: the main body of the boxplot showing the quartiles
               and the median's confidence intervals if enabled.
@@ -5032,6 +5034,7 @@ def pcolormesh(self, *args, **kwargs):
 
           *edgecolors*: [*None* | ``'None'`` | ``'face'`` | color |
                          color sequence]
+
             If *None*, the rc setting is used by default.
 
             If ``'None'``, edges will not be visible.

lib/matplotlib/cbook.py

@@ -122,9 +122,12 @@ def new_function():
 
     Examples
     --------
-    # To warn of the deprecation of "matplotlib.name_of_module"
-    warn_deprecated('1.4.0', name='matplotlib.name_of_module',
-                    obj_type='module')
+
+        Basic example::
+
+            # To warn of the deprecation of "matplotlib.name_of_module"
+            warn_deprecated('1.4.0', name='matplotlib.name_of_module',
+                            obj_type='module')
 
     """
     message = _generate_deprecation_message(
@@ -174,9 +177,12 @@ def new_function():
 
     Examples
     --------
-    @deprecated('1.4.0')
-    def the_function_to_deprecate():
-        pass
+
+        Basic example::
+
+            @deprecated('1.4.0')
+            def the_function_to_deprecate():
+                pass
 
     """
     def deprecate(func, message=message, name=name, alternative=alternative,
@@ -1911,7 +1917,7 @@ def boxplot_stats(X, whis=1.5, bootstrap=None, labels=None):
 
     General approach from:
     McGill, R., Tukey, J.W., and Larsen, W.A. (1978) "Variations of
-        Boxplots", The American Statistician, 32:12-16.
+    Boxplots", The American Statistician, 32:12-16.
 
     '''
 

lib/matplotlib/lines.py

@@ -937,6 +937,7 @@ def set_linestyle(self, linestyle):
 
         ACCEPTS: [``'-'`` | ``'--'`` | ``'-.'`` | ``':'`` | ``'None'`` |
                   ``' '`` | ``''``]
+
         and any drawstyle in combination with a linestyle, e.g., ``'steps--'``.
         """
 

lib/matplotlib/mlab.py

@@ -394,6 +394,7 @@ def demean(x, axis=0):
     .. seealso::
 
         :func:`delinear`
+
         :func:`denone`
             :func:`delinear` and :func:`denone` are other detrend algorithms.
 
@@ -427,6 +428,7 @@ def detrend_mean(x, axis=None):
             for the default *axis*.
 
         :func:`detrend_linear`
+
         :func:`detrend_none`
             :func:`detrend_linear` and :func:`detrend_none` are other
             detrend algorithms.
@@ -474,6 +476,7 @@ def detrend_none(x, axis=None):
             for the default *axis*, which has no effect.
 
         :func:`detrend_mean`
+
         :func:`detrend_linear`
             :func:`detrend_mean` and :func:`detrend_linear` are other
             detrend algorithms.
@@ -506,6 +509,7 @@ def detrend_linear(y):
             for the default *axis*.
 
         :func:`detrend_mean`
+
         :func:`detrend_none`
             :func:`detrend_mean` and :func:`detrend_none` are other
             detrend algorithms.
@@ -537,9 +541,11 @@ def stride_windows(x, n, noverlap=None, axis=0):
     Get all windows of x with length n as a single array,
     using strides to avoid data duplication.
 
-    .. warning:: It is not safe to write to the output array.  Multiple
-    elements may point to the same piece of memory, so modifying one value may
-    change others.
+    .. warning::
+
+        It is not safe to write to the output array.  Multiple
+        elements may point to the same piece of memory,
+        so modifying one value may change others.
 
     Call signature::
 
@@ -599,9 +605,11 @@ def stride_repeat(x, n, axis=0):
     Repeat the values in an array in a memory-efficient manner.  Array x is
     stacked vertically n times.
 
-    .. warning:: It is not safe to write to the output array.  Multiple
-    elements may point to the same piece of memory, so modifying one value may
-    change others.
+    .. warning::
+
+        It is not safe to write to the output array.  Multiple
+        elements may point to the same piece of memory, so
+        modifying one value may change others.
 
     Call signature::
 
@@ -878,6 +886,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
 
       *detrend*: [ 'default' | 'constant' | 'mean' | 'linear' | 'none'] or
                  callable
+
           The function applied to each segment before fft-ing,
           designed to remove the mean or linear trend.  Unlike in
           MATLAB, where the *detrend* parameter is a vector, in
@@ -1244,6 +1253,7 @@ def specgram(x, NFFT=None, Fs=None, detrend=None, window=None,
 
       *mode*: [ 'default' | 'psd' | 'complex' | 'magnitude'
                 'angle' | 'phase' ]
+
           What sort of spectrum to use.  Default is 'psd'. which takes the
           power spectral density.  'complex' returns the complex-valued
           frequency spectrum.  'magnitude' returns the magnitude spectrum.
@@ -1599,7 +1609,9 @@ def longest_ones(x):
 def prepca(P, frac=0):
     """
 
-    WARNING: this function is deprecated -- please see class PCA instead
+    .. warning::
+
+        This function is deprecated -- please see class PCA instead
 
     Compute the principal components of *P*.  *P* is a (*numVars*,
     *numObs*) array.  *frac* is the minimum fraction of variance that a

lib/matplotlib/pyplot.py

@@ -1311,17 +1311,24 @@ def title(s, *args, **kwargs):
     positioned above the axes in the center, flush with the left edge,
     and flush with the right edge.
 
+    .. seealso::
+        See :func:`~matplotlib.pyplot.text` for adding text
+        to the current axes
+
     Parameters
     ----------
     label : str
         Text to use for the title
+
     fontdict : dict
         A dictionary controlling the appearance of the title text,
         the default `fontdict` is:
-        {'fontsize': rcParams['axes.titlesize'],
-         'fontweight' : rcParams['axes.titleweight'],
-         'verticalalignment': 'baseline',
-         'horizontalalignment': loc}
+
+            {'fontsize': rcParams['axes.titlesize'],
+            'fontweight' : rcParams['axes.titleweight'],
+            'verticalalignment': 'baseline',
+            'horizontalalignment': loc}
+
     loc : {'center', 'left', 'right'}, str, optional
         Which title to set, defaults to 'center'
 
@@ -1332,13 +1339,10 @@ def title(s, *args, **kwargs):
 
     Other parameters
     ----------------
-    Other keyword arguments are text properties, see
-    :class:`~matplotlib.text.Text` for a list of valid text
-    properties.
-
-    See also
-    --------
-    See :func:`~matplotlib.pyplot.text` for adding text to the current axes
+    kwargs : text properties
+        Other keyword arguments are text properties, see
+        :class:`~matplotlib.text.Text` for a list of valid text
+        properties.
 
     """
     l =  gca().set_title(s, *args, **kwargs)

lib/matplotlib/tri/trirefine.py

@@ -37,6 +37,7 @@ class TriRefiner(object):
                 :class:`~matplotlib.tri.TriInterpolator` (optional)
               - the other optional keyword arguments *kwargs* are defined in
                 each TriRefiner concrete implementation
+
           and which returns (as a tuple) a refined triangular mesh and the
           interpolated values of the field at the refined triangulation nodes.
 

lib/mpl_toolkits/mplot3d/art3d.py

@@ -436,9 +436,12 @@ def patch_collection_2d_to_3d(col, zs=0, zdir='z', depthshade=True):
     :class:`Path3DCollection` object).
 
     Keywords:
+
     *za*            The location or locations to place the patches in the
                     collection along the *zdir* axis. Defaults to 0.
+
     *zdir*          The axis in which to place the patches. Default is "z".
+
     *depthshade*    Whether to shade the patches to give a sense of depth.
                     Defaults to *True*.