Merge pull request #14094 from meeseeksmachine/auto-backport-of-pr-14029-on-v3.1.x

tacaswell · web-flow · commit ce0afb929668 · 2019-04-29T19:35:44.000-04:00
Backport PR #14029 on branch v3.1.x (Fix doc building with numpydoc 0.9)
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -1461,6 +1461,12 @@ def _label_from_arg(y, default_name):
     return None
 
 
+_DATA_DOC_TITLE = """
+
+Notes
+-----
+"""
+
 _DATA_DOC_APPENDIX = """
 
 .. note::
@@ -1498,7 +1504,10 @@ def _add_data_doc(docstring, replace_names):
             if len(replace_names) == 0 else
             "* All arguments with the following names: {}.".format(
                 ", ".join(map(repr, sorted(replace_names)))))
-    return docstring + _DATA_DOC_APPENDIX.format(replaced=repl)
+    addendum = _DATA_DOC_APPENDIX.format(replaced=repl)
+    if _DATA_DOC_TITLE not in docstring:
+        addendum = _DATA_DOC_TITLE + addendum
+    return docstring + addendum
 
 
 def _preprocess_data(func=None, *, replace_names=None, label_namer=None):
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -2623,11 +2623,6 @@ def broken_barh(self, xranges, yrange, **kwargs):
         Returns
         -------
         collection : A :class:`~.collections.BrokenBarHCollection`
-
-        Notes
-        -----
-        .. [Notes section required for data comment. See #10189.]
-
         """
         # process the unit information
         if len(xranges):
@@ -3191,10 +3186,6 @@ def errorbar(self, x, y, yerr=None, xerr=None,
 
         %(_Line2D_docstr)s
 
-        Notes
-        -----
-        .. [Notes section required for data comment. See #10189.]
-
         """
         kwargs = cbook.normalize_kwargs(kwargs, mlines.Line2D._alias_map)
         # anything that comes in as 'None', drop so the default thing
@@ -3649,10 +3640,6 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
 
           - ``means``: points or lines representing the means.
 
-        Notes
-        -----
-        .. [Notes section required for data comment. See #10189.]
-
         """
 
         # Missing arguments default to rcParams.
@@ -6628,10 +6615,6 @@ 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
@@ -7353,10 +7336,6 @@ def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None,
             :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 Fc is None:
             Fc = 0
@@ -7442,10 +7421,6 @@ def angle_spectrum(self, x, Fs=None, Fc=None, window=None,
             :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 Fc is None:
             Fc = 0
@@ -7518,10 +7493,6 @@ def phase_spectrum(self, x, Fs=None, Fc=None, window=None,
             :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 Fc is None:
             Fc = 0
@@ -8031,10 +8002,6 @@ def violinplot(self, dataset, positions=None, vert=True, widths=0.5,
               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/cbook/deprecation.py b/lib/matplotlib/cbook/deprecation.py
@@ -250,12 +250,12 @@ def wrapper(*args, **kwargs):
 
         old_doc = inspect.cleandoc(old_doc or '').strip('\n')
 
-        message = message.strip()
-        new_doc = ('[*Deprecated*] {old_doc}\n'
-                   '\n'
-                   '.. deprecated:: {since}\n'
-                   '   {message}'
-                   .format(since=since, message=message, old_doc=old_doc))
+        notes_header = '\nNotes\n-----'
+        new_doc = (f"[*Deprecated*] {old_doc}\n"
+                   f"{notes_header if notes_header not in old_doc else ''}\n"
+                   f".. deprecated:: {since}\n"
+                   f"   {message.strip()}")
+
         if not old_doc:
             # This is to prevent a spurious 'unexpected unindent' warning from
             # docutils when the original docstring was blank.
diff --git a/requirements/doc/doc-requirements.txt b/requirements/doc/doc-requirements.txt
@@ -11,7 +11,7 @@ sphinx>=1.3,!=1.5.0,!=1.6.4,!=1.7.3,!=1.8.0<2.0.0
 colorspacious
 ipython
 ipywidgets
-numpydoc>=0.8,<0.9
+numpydoc>=0.8
 pillow>=3.4,!=5.4.0
 sphinx-gallery>=0.2
 sphinx-copybutton
