Merge pull request #4899 from sargas/remove-kwdocd-in-devel-doc

tacaswell · tacaswell · commit 7900ee4d4714 · 2015-08-11T00:04:34.000-04:00
DOC: Replace kwdocd in docs with docstring.interpd/dedent_interpd
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -86,21 +86,23 @@ function that takes a ``**kwargs``.  The requirements are:
 2. as automated as possible so that as properties change, the docs
    are updated automagically.
 
-The functions :attr:`matplotlib.artist.kwdocd` and
-:func:`matplotlib.artist.kwdoc` to facilitate this.  They combine
+The function :func:`matplotlib.artist.kwdoc` and the decorator
+:func:`matplotlib.docstring.dedent_interpd` facilitate this.  They combine
 python string interpolation in the docstring with the matplotlib
 artist introspection facility that underlies ``setp`` and ``getp``.
-The ``kwdocd`` is a single dictionary that maps class name to a
-docstring of ``kwargs``.  Here is an example from
+The ``kwdoc`` function gives the list of properties as a docstring. In order
+to use this in another docstring, first update the
+``matplotlib.docstring.interpd`` object, as seen in this example from
 :mod:`matplotlib.lines`::
 
   # in lines.py
-  artist.kwdocd['Line2D'] = artist.kwdoc(Line2D)
+  docstring.interpd.update(Line2D=artist.kwdoc(Line2D))
 
 Then in any function accepting :class:`~matplotlib.lines.Line2D`
 pass-through ``kwargs``, e.g., :meth:`matplotlib.axes.Axes.plot`::
 
   # in axes.py
+  @docstring.dedent_interpd
   def plot(self, *args, **kwargs):
       """
       Some stuff omitted
@@ -114,7 +116,6 @@ pass-through ``kwargs``, e.g., :meth:`matplotlib.axes.Axes.plot`::
       information
       """
       pass
-  plot.__doc__ = cbook.dedent(plot.__doc__) % artist.kwdocd
 
 Note there is a problem for :class:`~matplotlib.artist.Artist`
 ``__init__`` methods, e.g., :meth:`matplotlib.patches.Patch.__init__`,
@@ -123,7 +124,7 @@ work until the class is fully defined and we can't modify the
 ``Patch.__init__.__doc__`` docstring outside the class definition.
 There are some some manual hacks in this case, violating the
 "single entry point" requirement above -- see the
-``artist.kwdocd['Patch']`` setting in :mod:`matplotlib.patches`.
+``docstring.interpd.update`` calls in :mod:`matplotlib.patches`.
 
 .. _formatting-mpl-docs:
 
