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 pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy