Merge pull request matplotlib#22779 from oscargus/mlabdocumentation

DOC: Improve mlab documentation (and example)

Author: tacaswell

examples/lines_bars_and_markers/csd_demo.py

@@ -38,5 +38,5 @@
 ax1.grid(True)
 
 cxy, f = ax2.csd(s1, s2, 256, 1. / dt)
-ax2.set_ylabel('CSD (db)')
+ax2.set_ylabel('CSD (dB)')
 plt.show()

lib/matplotlib/mlab.py

@@ -60,7 +60,7 @@
 
 def window_hanning(x):
     """
-    Return x times the hanning window of len(x).
+    Return *x* times the Hanning (or Hann) window of len(*x*).
 
     See Also
     --------
@@ -71,7 +71,7 @@ def window_hanning(x):
 
 def window_none(x):
     """
-    No window function; simply return x.
+    No window function; simply return *x*.
 
     See Also
     --------
@@ -82,7 +82,7 @@ def window_none(x):
 
 def detrend(x, key=None, axis=None):
     """
-    Return x with its trend removed.
+    Return *x* with its trend removed.
 
     Parameters
     ----------
@@ -131,7 +131,7 @@ def detrend(x, key=None, axis=None):
 
 def detrend_mean(x, axis=None):
     """
-    Return x minus the mean(x).
+    Return *x* minus the mean(*x*).
 
     Parameters
     ----------
@@ -140,7 +140,7 @@ def detrend_mean(x, axis=None):
         Can have any dimensionality
 
     axis : int
-        The axis along which to take the mean.  See numpy.mean for a
+        The axis along which to take the mean.  See `numpy.mean` for a
         description of this argument.
 
     See Also
@@ -159,7 +159,7 @@ def detrend_mean(x, axis=None):
 
 def detrend_none(x, axis=None):
     """
-    Return x: no detrending.
+    Return *x*: no detrending.
 
     Parameters
     ----------
@@ -181,7 +181,7 @@ def detrend_none(x, axis=None):
 
 def detrend_linear(y):
     """
-    Return x minus best fit line; 'linear' detrending.
+    Return *x* minus best fit line; 'linear' detrending.
 
     Parameters
     ----------
@@ -216,7 +216,7 @@ def detrend_linear(y):
 @_api.deprecated("3.6")
 def stride_windows(x, n, noverlap=None, axis=0):
     """
-    Get all windows of x with length n as a single array,
+    Get all windows of *x* with length *n* as a single array,
     using strides to avoid data duplication.
 
     .. warning::
@@ -497,8 +497,8 @@ def _single_spectrum_helper(
     the FFT.  While not increasing the actual resolution of the spectrum (the
     minimum distance between resolvable peaks), this can give more points in
     the plot, allowing for more detail. This corresponds to the *n* parameter
-    in the call to fft().  The default is None, which sets *pad_to* equal to
-    the length of the input signal (i.e. no padding).""",
+    in the call to `~numpy.fft.fft`.  The default is None, which sets *pad_to*
+    equal to the length of the input signal (i.e. no padding).""",
 
     PSD="""\
 pad_to : int, optional
@@ -507,8 +507,8 @@ def _single_spectrum_helper(
     of data points used.  While not increasing the actual resolution of the
     spectrum (the minimum distance between resolvable peaks), this can give
     more points in the plot, allowing for more detail. This corresponds to
-    the *n* parameter in the call to fft(). The default is None, which sets
-    *pad_to* equal to *NFFT*
+    the *n* parameter in the call to `~numpy.fft.fft`. The default is None,
+    which sets *pad_to* equal to *NFFT*
 
 NFFT : int, default: 256
     The number of data points used in each block for the FFT.  A power 2 is
@@ -526,7 +526,7 @@ def _single_spectrum_helper(
 
 scale_by_freq : bool, default: True
     Whether the resulting density values should be scaled by the scaling
-    frequency, which gives density in units of Hz^-1.  This allows for
+    frequency, which gives density in units of 1/Hz.  This allows for
     integration over the returned frequency values.  The default is True for
     MATLAB compatibility.""")
 
@@ -714,11 +714,11 @@ def specgram(x, NFFT=None, Fs=None, detrend=None, window=None,
     """
     Compute a spectrogram.
 
-    Compute and plot a spectrogram of data in x.  Data are split into
-    NFFT length segments and the spectrum of each section is
-    computed.  The windowing function window is applied to each
+    Compute and plot a spectrogram of data in *x*.  Data are split into
+    *NFFT* length segments and the spectrum of each section is
+    computed.  The windowing function *window* is applied to each
     segment, and the amount of overlap of each segment is
-    specified with noverlap.
+    specified with *noverlap*.
 
     Parameters
     ----------
@@ -760,13 +760,13 @@ def specgram(x, NFFT=None, Fs=None, detrend=None, window=None,
     --------
     psd : differs in the overlap and in the return values.
     complex_spectrum : similar, but with complex valued frequencies.
-    magnitude_spectrum : similar single segment when mode is 'magnitude'.
-    angle_spectrum : similar to single segment when mode is 'angle'.
-    phase_spectrum : similar to single segment when mode is 'phase'.
+    magnitude_spectrum : similar single segment when *mode* is 'magnitude'.
+    angle_spectrum : similar to single segment when *mode* is 'angle'.
+    phase_spectrum : similar to single segment when *mode* is 'phase'.
 
     Notes
     -----
-    detrend and scale_by_freq only apply when *mode* is set to 'psd'.
+    *detrend* and *scale_by_freq* only apply when *mode* is set to 'psd'.
 
     """
     if noverlap is None: