From 6f4058b5acbcf1dcf0a4441d350b15d52434fe1e Mon Sep 17 00:00:00 2001 From: David Stansby Date: Wed, 24 Apr 2019 17:30:51 +0100 Subject: [PATCH 1/4] Fix doc building with numpydoc 0.9 --- lib/matplotlib/__init__.py | 11 ++++++++++- lib/matplotlib/cbook/deprecation.py | 14 +++++++++----- requirements/doc/doc-requirements.txt | 2 +- 3 files changed, 20 insertions(+), 7 deletions(-) diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py index 4069a88e4884..d4101ccba032 100644 --- 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 index 8920e55044fc..bb597ea6c9e0 100644 --- 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 index b42ec77568b1..66c0e97dca48 100644 --- 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 From 93e873b912f27b71d082fbf78d7ad9bee68ece53 Mon Sep 17 00:00:00 2001 From: David Stansby Date: Thu, 25 Apr 2019 09:21:35 +0100 Subject: [PATCH 2/4] Fix newlines --- lib/matplotlib/cbook/deprecation.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/matplotlib/cbook/deprecation.py b/lib/matplotlib/cbook/deprecation.py index bb597ea6c9e0..07ce232207cc 100644 --- a/lib/matplotlib/cbook/deprecation.py +++ b/lib/matplotlib/cbook/deprecation.py @@ -250,9 +250,9 @@ def wrapper(*args, **kwargs): message = message.strip() # Add "Deprecated" to top of docstring - new_doc = '[*Deprecated*] {old_doc}\n\n'.format(old_doc=old_doc) + new_doc = '[*Deprecated*] {old_doc}\n'.format(old_doc=old_doc) # Add a notes section if one isn't already present - note_section = 'Notes\n-----' + note_section = '\nNotes\n-----' if note_section not in new_doc: new_doc += note_section # Add deprecated message From ced88104c7e7c6638f35bdc202faadecc8752ca5 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Fri, 26 Apr 2019 11:10:05 +0200 Subject: [PATCH 3/4] More compact doc formatting --- lib/matplotlib/cbook/deprecation.py | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/lib/matplotlib/cbook/deprecation.py b/lib/matplotlib/cbook/deprecation.py index 07ce232207cc..cc7a26891b8f 100644 --- a/lib/matplotlib/cbook/deprecation.py +++ b/lib/matplotlib/cbook/deprecation.py @@ -248,16 +248,12 @@ def wrapper(*args, **kwargs): old_doc = inspect.cleandoc(old_doc or '').strip('\n') - message = message.strip() - # Add "Deprecated" to top of docstring - new_doc = '[*Deprecated*] {old_doc}\n'.format(old_doc=old_doc) - # Add a notes section if one isn't already present - note_section = '\nNotes\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)) + 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. From ad61f80bcca8674ae9ae7f2c65bfd9e528e7300a Mon Sep 17 00:00:00 2001 From: David Stansby Date: Mon, 29 Apr 2019 11:56:04 +0100 Subject: [PATCH 4/4] Remove manually added notes sections --- lib/matplotlib/axes/_axes.py | 33 --------------------------------- 1 file changed, 33 deletions(-) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 0ffb993440c2..65c216f6cff6 100644 --- 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):