From ab9d93d866a103d06ac6fafdf86a6340cdad84af Mon Sep 17 00:00:00 2001 From: hannah Date: Thu, 22 Aug 2024 01:37:54 -0400 Subject: [PATCH 1/2] document how to created interpolated stubs --- doc/devel/document.rst | 36 +++++++++++++++++++++++++++++------- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/doc/devel/document.rst b/doc/devel/document.rst index 81b44a830c34..d97111e61d1f 100644 --- a/doc/devel/document.rst +++ b/doc/devel/document.rst @@ -730,13 +730,6 @@ hiding it from the rendered docs. Keyword arguments ----------------- -.. note:: - - The information in this section is being actively discussed by the - development team, so use the docstring interpolation only if necessary. - This section has been left in place for now because this interpolation - is part of the existing documentation. - Since Matplotlib uses a lot of pass-through ``kwargs``, e.g., in every function that creates a line (`~.pyplot.plot`, `~.pyplot.semilogx`, `~.pyplot.semilogy`, etc.), it can be difficult for the new user to know which ``kwargs`` are @@ -797,6 +790,35 @@ point, `.kwdoc` can list the properties and interpolate them into ``__init__.__doc__``. +Create interpolated stubs +^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you are contributing code that will require keyword argument forwarding or creating +an object that may be returned in many places, such as the `.Line2D` artist, then you +may want to create docstrings that can be interpolated. To add documentation to the +``interpd`` lookup, add an identifier and the associated docstring: + +.. code-block:: python + + from matplotlib import _docstring + + _docstring.interpd.update(new_artist_doc="creates smiley faces") + +This now allows the string to be used in any docstring. For example: + +.. code-block:: python + + def plot(self, *args, **kwargs): + """ + **kwargs : new artist properties, optional + %(new_artist_doc)s + """ + + + + + + Inherit docstrings ------------------ From d5982a184698c71b8332f1b35ec342c0c37a5b76 Mon Sep 17 00:00:00 2001 From: hannah Date: Thu, 22 Aug 2024 15:08:10 -0400 Subject: [PATCH 2/2] --amend --- doc/devel/document.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/devel/document.rst b/doc/devel/document.rst index d97111e61d1f..19f677314e77 100644 --- a/doc/devel/document.rst +++ b/doc/devel/document.rst @@ -815,8 +815,8 @@ This now allows the string to be used in any docstring. For example: """ - - +The list of interpolated stubs is stored in the ``_docstring.interpd.params`` +dictionary. Inherit docstrings