8000 document how to created interpolated stubs · matplotlib/matplotlib@dc472c8 · GitHub
[go: up one dir, main page]

Skip to content

Commit dc472c8

Browse files
committed
document how to created interpolated stubs
1 parent 436a12a commit dc472c8

File tree

1 file changed

+29
-7
lines changed

1 file changed

+29
-7
lines changed

doc/devel/document.rst

Lines changed: 29 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -730,13 +730,6 @@ hiding it from the rendered docs.
730730
Keyword arguments
731731
-----------------
732732

733-
.. note::
734-
735-
The information in this section is being actively discussed by the
736-
development team, so use the docstring interpolation only if necessary.
737-
This section has been left in place for now because this interpolation
738-
is part of the existing documentation.
739-
740733
Since Matplotlib uses a lot of pass-through ``kwargs``, e.g., in every function
741734
that creates a line (`~.pyplot.plot`, `~.pyplot.semilogx`, `~.pyplot.semilogy`,
742735
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
797790
``__init__.__doc__``.
798791

799792

793+
Create interpolated stubs
794+
^^^^^^^^^^^^^^^^^^^^^^^^^
795+
796+
If you are contributing code that will require keyword argument forwarding or creating
797+
an object that may be returned in many places, such as the `.Line2D` artist, then you
798+
may want to create docstrings that can be interpolated. To add documentation to the
799+
``interpd`` lookup, add an identifier and the associated docstring:
800+
801+
.. code-block:: python
802+
803+
from matplotlib import _docstring
804+
805+
_docstring.interpd.update(new_artist_doc="creates smiley faces")
806+
807+
This now allows the string to be used in any docstring. For example:
808+
809+
.. code-block:: python
810+
811+
def plot(self, *args, **kwargs):
812+
"""
813+
**kwargs : new artist properties, optional
814+
%(new_artist_doc)s
815+
"""
816+
817+
818+
819+
820+
821+
800822
Inherit docstrings
801823
------------------
802824

0 commit comments

Comments
 (0)
0