Commit a284a54

committed

Write data parameter docs as regular parameter not as note (v2)

Replaces matplotlib#19859. This approach uses an explicit template ``` data : indexable object, optional # data_parameter_message ``` in the docstring and does not try to guess a reasonable insertion position based on the docstring content. This is much simpler.

1 parent 9b9c42d commit a284a54Copy full SHA for a284a54

File tree

7 files changed

+154

-29

lines changed

lib/matplotlib
- __init__.py
- axes
  - _axes.py
- contour.py
- quiver.py
- stackplot.py
- streamplot.py
- tests
  - test_matplotlib.py

7 files changed

+154

-29

lines changed

`‎lib/matplotlib/init.py`

Lines changed: 29 additions & 29 deletions

Original file line number	Diff line number	Diff line change
`@@ -1256,24 +1256,6 @@ def _label_from_arg(y, default_name):`
`1256`	`1256`	`return None`
`1257`	`1257`
`1258`	`1258`
`1259`		`-_DATA_DOC_TITLE = """`
`1260`		`-`
`1261`		`-Notes`
`1262`		`------`
`1263`		`-"""`
`1264`		`-`
`1265`		`-_DATA_DOC_APPENDIX = """`
`1266`		`-`
`1267`		`-.. note::`
`1268`		`- In addition to the above described arguments, this function can take`
`1269`		`- a data keyword argument. If such a data argument is given,`
`1270`		`-{replaced}`
`1271`		`-`
`1272`		- Objects passed as data must support item access (``data[s]``) and
`1273`		- membership test (``s in data``).
`1274`		`-"""`
`1275`		`-`
`1276`		`-`
`1277`	`1259`	`def _add_data_doc(docstring, replace_names):`
`1278`	`1260`	`"""`
`1279`	`1261`	`Add documentation for a data field to the given docstring.`
`@@ -1296,17 +1278,35 @@ def _add_data_doc(docstring, replace_names):`
`1296`	`1278`	`or replace_names is not None and len(replace_names) == 0):`
`1297`	`1279`	`return docstring`
`1298`	`1280`	`docstring = inspect.cleandoc(docstring)`
`1299`		`- repl = (`
`1300`		- (" every other argument can also be string ``s``, which is\n"
`1301`		- " interpreted as ``data[s]`` (unless this raises an exception).")
`1302`		`- if replace_names is None else`
`1303`		- (" the following arguments can also be string ``s``, which is\n"
`1304`		- " interpreted as ``data[s]`` (unless this raises an exception):\n"
`1305`		`- " " + ", ".join(map("{}".format, replace_names))) + ".")`
`1306`		`- addendum = _DATA_DOC_APPENDIX.format(replaced=repl)`
`1307`		`- if _DATA_DOC_TITLE not in docstring:`
`1308`		`- addendum = _DATA_DOC_TITLE + addendum`
`1309`		`- return docstring + addendum`
	`1281`	`+`
	`1282`	`+ data_doc = ("""\`
	`1283`	+ If given, all parameters also accept a string ``s``, which is
	`1284`	+ interpreted as ``data[s]`` (unless this raises an exception).
	`1285`	`+`
	`1286`	+ Objects passed as data must support item access (``data[s]``) and
	`1287`	+ membership test (``s in data``)."""
	`1288`	`+ if replace_names is None else ("""\`
	`1289`	+ If given, the following parameters also accept a string ``s``, which
	`1290`	+ is interpreted as ``data[s]`` (unless this raises an exception):
	`1291`	`+`
	`1292`	`+ {names}`
	`1293`	`+`
	`1294`	+ Objects passed as data must support item access (``data[s]``) and
	`1295`	+ membership test (``s in data``).""".format(
	`1296`	`+ names=", ".join(map("{}".format, replace_names)))`
	`1297`	`+ )`
	`1298`	`+ )`
	`1299`	`+ # using string replacement instead of formatting has the advantages`
	`1300`	`+ # 1) simpler indent handling`
	`1301`	`+ # 2) prevent problems with formatting characters '{', '%' in the docstring`
	`1302`	`+ if _log.level <= logging.DEBUG:`
	`1303`	`+ # test_data_parameter_replacement() tests against these log messages`
	`1304`	`+ # make sure to keep message and test in sync`
	`1305`	`+ if "data : indexable object, optional" not in docstring:`
	`1306`	`+ _log.debug("data parameter docstring error: no data parameter")`
	`1307`	`+ if '# data_parameter_message' not in docstring:`
	`1308`	`+ _log.debug("data parameter docstring error: missing placeholder")`
	`1309`	`+ return docstring.replace(' # data_parameter_message', data_doc)`
`1310`	`1310`
`1311`	`1311`
`1312`	`1312`	`def _preprocess_data(func=None, *, replace_names=None, label_namer=None):`

0 commit comments

Comments

(0)

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Commit a284a54

File tree

7 files changed

7 files changed

`‎lib/matplotlib/init.py`

0 commit comments

File tree

7 files changed

7 files changed

‎lib/matplotlib/__init__.py

0 commit comments

`‎lib/matplotlib/init.py`