matplotlib · anntzer · Apr 29, 2019 · Apr 24, 2019 · Apr 25, 2019 · Apr 26, 2019
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -1450,6 +1450,12 @@ def _label_from_arg(y, default_name):
     return None
 
 
+_DATA_DOC_TITLE = """
+
+Notes
+-----
+"""
+
 _DATA_DOC_APPENDIX = """
 
 .. note::
@@ -1487,7 +1493,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
@@ -2615,11 +2615,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):
@@ -3183,10 +3178,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)
         # anything that comes in as 'None', drop so the default thing
@@ -3641,10 +3632,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.
@@ -6579,10 +6566,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
@@ -7299,10 +7282,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
@@ -7388,10 +7367,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
@@ -7464,10 +7439,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
@@ -7966,10 +7937,6 @@ def violinplot(self, dataset, positions=None, vert=True, widths=0.5,
           - ``cmedians``: A `~.collections.LineCollection` instance that
             marks 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
@@ -248,12 +248,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.8.1,<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