8000 Write data parameter docs as regular parameter not as note · matplotlib/matplotlib@ee8f655 · GitHub
[go: up one dir, main page]
Skip to content

Commit ee8f655

Browse files
timhoffmtimhoffm
committed
Write data parameter docs as regular parameter not as note
1 parent 906cae4 commit ee8f655

File tree

2 files changed

+111
-22
lines changed

2 files changed

+111
-22
lines changed

‎lib/matplotlib/__init__.py

Lines changed: 34 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1247,20 +1247,12 @@ def _label_from_arg(y, default_name):
12471247
return None
12481248

12491249

1250-
_DATA_DOC_TITLE = """
1251-
1252-
Notes
1253-
-----
1254-
"""
1255-
1256-
_DATA_DOC_APPENDIX = """
1257-
1258-
.. note::
1259-
In addition to the above described arguments, this function can take
1260-
a *data* keyword argument. If such a *data* argument is given,
1250+
_DATA_KWARG = """\
1251+
data : indexable object, optional
1252+
If given,
12611253
{replaced}
12621254
1263-
Objects passed as **data** must support item access (``data[s]``) and
1255+
Objects passed as *data* must support item access (``data[s]``) and
12641256
membership test (``s in data``).
12651257
"""
12661258

@@ -1287,17 +1279,43 @@ def _add_data_doc(docstring, replace_names):
12871279
or replace_names is not None and len(replace_names) == 0):
12881280
return docstring
12891281
docstring = inspect.cleandoc(docstring)
1282+
1283+
def find_insert_index(docstring):
1284+
# Try inserting before **kwargs docs
1285+
insert_index = docstring.find('\n**kwargs') + 1
1286+
if insert_index > 0:
1287+
return insert_index
1288+
# If **kwargs docs does not exist, insert as the last parameter.
1289+
# To do so, find the end of the parameters section:
1290+
# - find start of parameters section
1291+
# - find next section (defined by a line starting with '----'). This
1292+
# seems the most reliable way as the parameters section may be quite
1293+
# complex.
1294+
# - Go back to the previous empty line (A section title must be
1295+
# preceededby an emtpy line.
1296+
param_string = '\nParameters\n----------\n'
1297+
i_params = docstring.find(param_string) + len(param_string)
1298+
i_next_heading = docstring.find('\n----', i_params)
1299+
if i_next_heading < 0:
1300+
return -1 # no next heading: append to end
1301+
insert_index = docstring.rfind('\n\n', i_params, i_next_heading) + 1
1302+
assert insert_index > 0
1303+
return insert_index
1304+
1305+
insert_index = find_insert_index(docstring)
12901306
repl = (
12911307
(" every other argument can also be string ``s``, which is\n"
12921308
" interpreted as ``data[s]`` (unless this raises an exception).")
12931309
if replace_names is None else
12941310
(" the following arguments can also be string ``s``, which is\n"
12951311
" interpreted as ``data[s]`` (unless this raises an exception):\n"
12961312
" " + ", ".join(map("*{}*".format, replace_names))) + ".")
1297-
addendum = _DATA_DOC_APPENDIX.format(replaced=repl)
1298-
if _DATA_DOC_TITLE not in docstring:
1299-
addendum = _DATA_DOC_TITLE + addendum
1300-
return docstring + addendum
1313+
if insert_index == -1:
1314+
return (docstring + '\n' + _DATA_KWARG.format(replaced=repl))
1315+
else:
1316+
return (docstring[:insert_index]
1317+
+ _DATA_KWARG.format(replaced=repl)
1318+
+ docstring[insert_index:])
13011319

13021320

13031321
def _preprocess_data(func=None, *, replace_names=None, label_namer=None):

‎lib/matplotlib/tests/test_preprocess_data.py

Lines changed: 77 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
import numpy as np
44
import pytest
55

6-
from matplotlib import _preprocess_data
6+
from matplotlib import _add_data_doc, _preprocess_data
77
from matplotlib.axes import Axes
88
from matplotlib.testing.decorators import check_figures_equal
99

@@ -194,10 +194,69 @@ def func(ax, x, y, z=1):
194194
func(None, "a", "b", "z", "z", data=data)
195195

196196

197+
def test_add_data_doc_kwargs():
198+
"""Test that the data docs is inserted before **kwargs."""
199+
assert ("Data param should follow.\ndata : indexable object, optional" in
200+
_add_data_doc("""\
201+
Some function.
202+
203+
Parameters
204+
----------
205+
x
206+
Data param should follow.
207+
**kwargs
208+
Additional parameters.
209+
""", replace_names=['x']))
210+
211+
212+
def test_add_data_doc_after_params():
213+
"""
214+
Test that the data docs is inserted at the end of Parameters section
215+
that is followed by another section.
216+
"""
217+
assert ("Data param should follow.\ndata : indexable object, optional" in
218+
_add_data_doc("""\
219+
Some function.
220+
221+
Parameters
222+
----------
223+
x
224+
Data param should follow.
225+
226+
Returns
227+
-------
228+
someting
229+
""", replace_names=['x']))
230+
231+
232+
def test_add_data_doc_after_params_last():
233+
"""
234+
Test that the data docs is inserted at the end of Parameters section
235+
that is not followed by further docs.
236+
"""
237+
assert ("Data param should follow.\ndata : indexable object, optional" in
238+
_add_data_doc("""\
239+
Some function.
240+
241+
Parameters
242+
----------
243+
x
244+
Data param should follow.
245+
""", replace_names=['x']))
246+
247+
248+
197249
def test_docstring_addition():
198250
@_preprocess_data()
199251
def funcy(ax, *args, **kwargs):
200-
"""Funcy does nothing"""
252+
"""
253+
Funcy does nothing.
254+
255+
Parameters
256+
----------
257+
**kwargs
258+
Text.
259+
"""
201260

202261
assert re.search(r"every other argument", funcy.__doc__)
203262
assert not re.search(r"the following arguments", funcy.__doc__)
@@ -211,16 +270,28 @@ def funcy(ax, x, y, z, bar=None):
211270

212271
@_preprocess_data(replace_names=["bar"])
213272
def funcy(ax, x, y, z, bar=None):
214-
"""Funcy does nothing"""
215-
273+
"""
274+
Funcy does nothing.
275+
276+
Parameters
277+
----------
278+
**kwargs
279+
Text.
280+
"""
216281
assert not re.search(r"every other argument", funcy.__doc__)
217282
assert not re.search(r"the following arguments .*: \*bar\*\.",
218283
funcy.__doc__)
219284

220285
@_preprocess_data(replace_names=["x", "t"])
221286
def funcy(ax, x, y, z, t=None):
222-
"""Funcy does nothing"""
223-
287+
"""
288+
Funcy does nothing.
289+
290+
Parameters
291+
----------
292+
x, y, z
293+
Text.
294+
"""
224295
assert not re.search(r"every other argument", funcy.__doc__)
225296
assert not re.search(r"the following arguments .*: \*x\*, \*t\*\.",
226297
funcy.__doc__)

0 commit comments

Comments
 (0)
0