Merge pull request #10366 from timhoffm/axes-doc-datanotes

dstansby · web-flow · commit 6547c122f266 · 2018-02-09T12:33:30.000Z
Axes doc datanotes
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -676,6 +676,11 @@ def axhline(self, y=0, xmin=0, xmax=1, **kwargs):
 
             %(Line2D)s
 
+        See also
+        --------
+        hlines : add horizontal lines in data coordinates
+        axhspan : add a horizontal span (rectangle) across the axis
+
         Notes
         -----
         kwargs are passed to :class:`~matplotlib.lines.Line2D` and can be used
@@ -697,12 +702,7 @@ def axhline(self, y=0, xmin=0, xmax=1, **kwargs):
 
             >>> axhline(y=.5, xmin=0.25, xmax=0.75)
 
-        See also
-        --------
-        hlines : add horizontal lines in data coordinates
-        axhspan : add a horizontal span (rectangle) across the axis
         """
-
         if "transform" in kwargs:
             raise ValueError(
                 "'transform' is not allowed as a kwarg;"
@@ -2826,10 +2826,7 @@ def pie(self, x, explode=None, labels=None, colors=None,
         -----
         The pie chart will probably look best if the figure and axes are
         square, or the Axes aspect is equal.
-
-
         """
-
         x = np.array(x, np.float32)
 
         sx = x.sum()
@@ -4457,7 +4454,7 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
             to the return collection as attributes *hbar* and *vbar*.
 
         Notes
-        --------
+        -----
         The standard descriptions of all the
         :class:`~matplotlib.collections.Collection` parameters:
 
@@ -6405,6 +6402,10 @@ def hist(self, x, bins=None, range=None, density=None, weights=None,
         --------
         hist2d : 2D histograms
 
+        Notes
+        -----
+        .. [Notes section required for data comment. See #10189.]
+
         """
         # Avoid shadowing the builtin.
         bin_range = range
@@ -6884,17 +6885,6 @@ def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
 
             %(Line2D)s
 
-        Notes
-        -----
-        For plotting, the power is plotted as
-        :math:`10\log_{10}(P_{xx})` for decibels, though *Pxx* itself
-        is returned.
-
-        References
-        ----------
-        Bendat & Piersol -- Random Data: Analysis and Measurement Procedures,
-        John Wiley & Sons (1986)
-
         See Also
         --------
         :func:`specgram`
@@ -6907,6 +6897,17 @@ def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
 
         :func:`csd`
             :func:`csd` plots the spectral density between two signals.
+
+        Notes
+        -----
+        For plotting, the power is plotted as
+        :math:`10\log_{10}(P_{xx})` for decibels, though *Pxx* itself
+        is returned.
+
+        References
+        ----------
+        Bendat & Piersol -- Random Data: Analysis and Measurement Procedures,
+        John Wiley & Sons (1986)
         """
         if not self._hold:
             self.cla()
@@ -7012,6 +7013,11 @@ def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None,
 
             %(Line2D)s
 
+        See Also
+        --------
+        :func:`psd`
+            :func:`psd` is the equivalent to setting y=x.
+
         Notes
         -----
         For plotting, the power is plotted as
@@ -7022,11 +7028,6 @@ def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None,
         ----------
         Bendat & Piersol -- Random Data: Analysis and Measurement Procedures,
         John Wiley & Sons (1986)
-
-        See Also
-        --------
-        :func:`psd`
-            :func:`psd` is the equivalent to setting y=x.
         """
         if not self._hold:
             self.cla()
@@ -7129,6 +7130,11 @@ def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None,
         :func:`specgram`
             :func:`specgram` can plot the magnitude spectrum of segments within
             the signal in a colormap.
+
+        Notes
+        -----
+        .. [Notes section required for data comment. See #10189.]
+
         """
         if not self._hold:
             self.cla()
@@ -7221,6 +7227,11 @@ def angle_spectrum(self, x, Fs=None, Fc=None, window=None,
         :func:`specgram`
             :func:`specgram` can plot the angle spectrum of segments within the
             signal in a colormap.
+
+        Notes
+        -----
+        .. [Notes section required for data comment. See #10189.]
+
         """
         if not self._hold:
             self.cla()
@@ -7300,6 +7311,11 @@ def phase_spectrum(self, x, Fs=None, Fc=None, window=None,
         :func:`specgram`
             :func:`specgram` can plot the phase spectrum of segments within the
             signal in a colormap.
+
+        Notes
+        -----
+        .. [Notes section required for data comment. See #10189.]
+
         """
         if not self._hold:
             self.cla()
@@ -7456,11 +7472,6 @@ def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
             Additional kwargs are passed on to imshow which makes the
             specgram image
 
-        Notes
-        -----
-            *detrend* and *scale_by_freq* only apply when *mode* is set to
-            'psd'
-
         Returns
         -------
         spectrum : 2-D array
@@ -7494,6 +7505,11 @@ def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
         :func:`phase_spectrum`
             A single spectrum, similar to having a single segment when *mode*
             is 'phase'. Plots a line instead of a colormap.
+
+        Notes
+        -----
+        The parameters *detrend* and *scale_by_freq* do only apply when *mode*
+        is set to 'psd'.
         """
         if not self._hold:
             self.cla()
@@ -7788,6 +7804,11 @@ def violinplot(self, dataset, positions=None, vert=True, widths=0.5,
               :class:`matplotlib.collections.LineCollection` instance
               created to identify the median values of each of the
               violin's distribution.
+
+        Notes
+        -----
+        .. [Notes section required for data comment. See #10189.]
+
         """
 
         def _kde_method(X, coords):
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -624,7 +624,6 @@ def autofmt_xdate(self, bottom=0.2, rotation=30, ha='right', which=None):
 
         Parameters
         ----------
-
         bottom : scalar
             The bottom of the subplots for :meth:`subplots_adjust`
 
@@ -660,7 +659,7 @@ def autofmt_xdate(self, bottom=0.2, rotation=30, ha='right', which=None):
         self.stale = True
 
     def get_children(self):
-        'get a list of artists contained in the figure'
+        """Get a list of artists contained in the figure."""
         children = [self.patch]
         children.extend(self.artists)
         children.extend(self.axes)
@@ -683,9 +682,9 @@ def contains(self, mouseevent):
         return inside, {}
 
     def get_window_extent(self, *args, **kwargs):
-        ''''
+        """
         Return figure bounding box in display space; arguments are ignored.
-        '''
+        """
         return self.bbox
 
     def suptitle(self, t, **kwargs):
@@ -886,7 +885,6 @@ def set_size_inches(self, w, h=None, forward=True):
 
         See Also
         --------
-
         matplotlib.Figure.get_size_inches
         """
 
@@ -923,33 +921,32 @@ def get_size_inches(self):
 
         See Also
         --------
-
         matplotlib.Figure.set_size_inches
         """
         return np.array(self.bbox_inches.p1)
 
     def get_edgecolor(self):
-        'Get the edge color of the Figure rectangle'
+        """Get the edge color of the Figure rectangle."""
         return self.patch.get_edgecolor()
 
     def get_facecolor(self):
-        'Get the face color of the Figure rectangle'
+        """Get the face color of the Figure rectangle."""
         return self.patch.get_facecolor()
 
     def get_figwidth(self):
-        'Return the figwidth as a float'
+        """Return the figwidth as a float."""
         return self.bbox_inches.width
 
     def get_figheight(self):
-        'Return the figheight as a float'
+        """Return the figheight as a float."""
         return self.bbox_inches.height
 
     def get_dpi(self):
-        'Return the dpi as a float'
+        """Return the dpi as a float."""
         return self.dpi
 
     def get_frameon(self):
-        'get the boolean indicating frameon'
+        """Get the boolean indicating frameon."""
         return self.frameon
 
     def set_edgecolor(self, color):
@@ -1012,7 +1009,7 @@ def delaxes(self, ax):
         self.stale = True
 
     def _make_key(self, *args, **kwargs):
-        'make a hashable key out of args and kwargs'
+        """Make a hashable key out of args and kwargs."""
 
         def fixitems(items):
             # items may have arrays and lists in them, so convert them
@@ -1483,8 +1480,8 @@ def draw(self, renderer):
 
     def draw_artist(self, a):
         """
-        draw :class:`matplotlib.artist.Artist` instance *a* only --
-        this is available only after the figure is drawn
+        Draw :class:`matplotlib.artist.Artist` instance *a* only.
+        This is available only after the figure is drawn.
         """
         if self._cachedRenderer is None:
             raise AttributeError("draw_artist can only be used after an "
@@ -1817,16 +1814,15 @@ def gca(self, **kwargs):
         return self.add_subplot(1, 1, 1, **kwargs)
 
     def sca(self, a):
-        'Set the current axes to be a and return a'
+        """Set the current axes to be a and return a."""
         self._axstack.bubble(a)
         for func in self._axobservers:
             func(self)
         return a
 
     def _gci(self):
         """
-        helper for :func:`~matplotlib.pyplot.gci`;
-        do not use elsewhere.
+        Helper for :func:`~matplotlib.pyplot.gci`. Do not use elsewhere.
         """
         # Look first for an image in the current Axes:
         cax = self._axstack.current_key_axes()[1]
@@ -1924,7 +1920,7 @@ def make_active(event):
         self.stale = True
 
     def add_axobserver(self, func):
-        'whenever the axes state change, ``func(self)`` will be called'
+        """Whenever the axes state change, ``func(self)`` will be called."""
         self._axobservers.append(func)
 
     def savefig(self, fname, **kwargs):
@@ -2083,7 +2079,7 @@ def subplots_adjust(self, *args, **kwargs):
                               wspace=None, hspace=None)
 
         Update the :class:`SubplotParams` with *kwargs* (defaulting to rc when
-        *None*) and update the subplot locations
+        *None*) and update the subplot locations.
 
         """
         self.subplotpars.update(*args, **kwargs)
@@ -2246,7 +2242,6 @@ def tight_layout(self, renderer=None, pad=1.08, h_pad=None, w_pad=None,
 
         Parameters
         ----------
-
         pad : float
             padding between the figure edge and the edges of subplots,
             as a fraction of the font-size.
@@ -2296,19 +2291,19 @@ def align_xlabels(self, axs=None):
             Optional list of (or ndarray) `~matplotlib.axes.Axes` to align
             the xlabels.  Default is to align all axes on the figure.
 
-        Note
-        ----
-        This assumes that ``axs`` are from the same `~.GridSpec`, so that
-        their `~.SubplotSpec` positions correspond to figure positions.
-
         See Also
         --------
         matplotlib.figure.Figure.align_ylabels
 
         matplotlib.figure.Figure.align_labels
 
-        Example
-        -------
+        Notes
+        -----
+        This assumes that ``axs`` are from the same `~.GridSpec`, so that
+        their `~.SubplotSpec` positions correspond to figure positions.
+
+        Examples
+        --------
         Example with rotated xtick labels::
 
             fig, axs = plt.subplots(1, 2)
@@ -2364,19 +2359,19 @@ def align_ylabels(self, axs=None):
             Optional list (or ndarray) of `~matplotlib.axes.Axes` to align
             the ylabels. Default is to align all axes on the figure.
 
-        Note
-        ----
-        This assumes that ``axs`` are from the same `~.GridSpec`, so that
-        their `~.SubplotSpec` positions correspond to figure positions.
-
         See Also
         --------
         matplotlib.figure.Figure.align_xlabels
 
         matplotlib.figure.Figure.align_labels
 
-        Example
-        -------
+        Notes
+        -----
+        This assumes that ``axs`` are from the same `~.GridSpec`, so that
+        their `~.SubplotSpec` positions correspond to figure positions.
+
+        Examples
+        --------
         Example with large yticks labels::
 
             fig, axs = plt.subplots(2, 1)
