Fix doc building with numpydoc 0.9

dstansby · dstansby · commit 6f4058b5acbc · 2019-04-24T17:30:51.000+01:00
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/cbook/deprecation.py b/lib/matplotlib/cbook/deprecation.py
@@ -249,11 +249,15 @@ 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))
+        # Add "Deprecated" to top of docstring
+        new_doc = '[*Deprecated*] {old_doc}\n\n'.format(old_doc=old_doc)
+        # Add a notes section if one isn't already present
+        note_section = 'Notes\n-----'
+        if note_section not in new_doc:
+            new_doc += note_section
+        # Add deprecated message
+        new_doc += ('\n.. deprecated:: {since}\n'
+                    '   {message}'.format(since=since, message=message))
         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
