Merge pull request matplotlib#20291 from timhoffm/data-kwarg-v2

Author: anntzer

lib/matplotlib/__init__.py

@@ -1256,24 +1256,6 @@ def _label_from_arg(y, default_name):
     return None
 
 
-_DATA_DOC_TITLE = """
-
-Notes
------
-"""
-
-_DATA_DOC_APPENDIX = """
-
-.. note::
-    In addition to the above described arguments, this function can take
-    a *data* keyword argument. If such a *data* argument is given,
-{replaced}
-
-    Objects passed as **data** must support item access (``data[s]``) and
-    membership test (``s in data``).
-"""
-
-
 def _add_data_doc(docstring, replace_names):
     """
     Add documentation for a *data* field to the given docstring.
@@ -1296,17 +1278,35 @@ def _add_data_doc(docstring, replace_names):
             or replace_names is not None and len(replace_names) == 0):
         return docstring
     docstring = inspect.cleandoc(docstring)
-    repl = (
-        ("    every other argument can also be string ``s``, which is\n"
-         "    interpreted as ``data[s]`` (unless this raises an exception).")
-        if replace_names is None else
-        ("    the following arguments can also be string ``s``, which is\n"
-         "    interpreted as ``data[s]`` (unless this raises an exception):\n"
-         "    " + ", ".join(map("*{}*".format, replace_names))) + ".")
-    addendum = _DATA_DOC_APPENDIX.format(replaced=repl)
-    if _DATA_DOC_TITLE not in docstring:
-        addendum = _DATA_DOC_TITLE + addendum
-    return docstring + addendum
+
+    data_doc = ("""\
+    If given, all parameters also accept a string ``s``, which is
+    interpreted as ``data[s]`` (unless this raises an exception).
+
+    Objects passed as **data** must support item access (``data[s]``) and
+    membership test (``s in data``)."""
+                if replace_names is None else ("""\
+    If given, the following parameters also accept a string ``s``, which
+    is interpreted as ``data[s]`` (unless this raises an exception):
+
+    {names}
+
+    Objects passed as **data** must support item access (``data[s]``) and
+    membership test (``s in data``).""".format(
+            names=", ".join(map("*{}*".format, replace_names)))
+        )
+    )
+    # using string replacement instead of formatting has the advantages
+    # 1) simpler indent handling
+    # 2) prevent problems with formatting characters '{', '%' in the docstring
+    if _log.level <= logging.DEBUG:
+        # test_data_parameter_replacement() tests against these log messages
+        # make sure to keep message and test in sync
+        if "data : indexable object, optional" not in docstring:
+            _log.debug("data parameter docstring error: no data parameter")
+        if 'DATA_PARAMETER_PLACEHOLDER' not in docstring:
+            _log.debug("data parameter docstring error: missing placeholder")
+    return docstring.replace('    DATA_PARAMETER_PLACEHOLDER', data_doc)
 
 
 def _preprocess_data(func=None, *, replace_names=None, label_namer=None):