Closed as not planned
Closed as not planned
Copy link
Labels
Documentationstatus: closed as inactiveIssues closed by the "Stale" Github Action. Please comment on any you think should still be open.Issues closed by the "Stale" Github Action. Please comment on any you think should still be open.status: inactiveMarked by the “Stale” Github ActionMarked by the “Stale” Github Action
Description
Bug report
After switching to the numpydoc format, it's a common situation that one wants to add a docstring interpolation to the a parameter entry, e.g.
@docstring.dedent_interpd
def axhline(self, y=0, xmin=0, xmax=1, **kwargs):
"""
Add a horizontal line across the axis.
[...]
Other Parameters
----------------
**kwargs :
Valid kwargs are :class:`~matplotlib.lines.Line2D` properties,
with the exception of 'transform':
%(Line2D)s
"""
The resulting docstring is:
Other Parameters
----------------
**kwargs :
Valid kwargs are :class:`~matplotlib.lines.Line2D` properties,
with the exception of 'transform':
agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha: float (0.0 transparent through 1.0 opaque)
animated: bool
[...]
Note that the first line agg_filter is correctly indented. However, the following inserted lines are missing the indent before the %(Line2D)s in the original string.
This is a general problem if the inserted string is multi-line (basically always) and the format string should be indented as in the parameter list.
Any clever ideas to get this working?
Metadata
Metadata
Assignees
Labels
Documentationstatus: closed as inactiveIssues closed by the "Stale" Github Action. Please comment on any you think should still be open.Issues closed by the "Stale" Github Action. Please comment on any you think should still be open.status: inactiveMarked by the “Stale” Github ActionMarked by the “Stale” Github Action
Activity
anntzer commentedon Jan 4, 2018
See #9414 for related discussion.
(FWIW I think it is not too hard to write a custom interpolator that checks the leading indentation and does the "right" thing)
anntzer commentedon Jan 5, 2018
As it turns out it is really easy to make interpolation respect indentation when using new-style ({}) formatting, see https://github.com/anntzer/structured-docstrings#interpolated-docstrings for an example implementation.
Don't have much time to relitigate the discussion in #9414 right now but I think a more robust interpolator may be a good first step...
timhoffm commentedon Feb 1, 2018
As proposed in #10274, we should consider expanding to a definition list, so that the parameters are rendered as if they were regularly written, i.e.
would become
I'm not quite decided, if this is a good idea.
On the one hand, it's nice to use the standard format. On the other hand, it may be clearer, to say that this whole group of parameters is just inherited from Line2D. This may help more experienced users, who already know the Line2D properties and don't have to scan the whole list to know what is available. Also it explains the existence of some maybe unexpected params like figure. Another technical aspect: I don't think we can link the parameter names themselves. We would need to use something else to link to the respective Line2D property for further information.
In sum, I tend to leave this as a table below the parameter
**kwargs.jklymak commentedon Mar 8, 2018
Where are we w/ this?
legendhas three identical docstrings, and I'd sure like to be able to use docstring interpolation...anntzer commentedon Mar 8, 2018
You may be interested in anntzer@0f72aa4 which was a start at converting to the new interpolation system I proposed above.
jklymak commentedon Mar 8, 2018
Very interested!
jklymak commentedon Mar 8, 2018
But in the meantime can I use
%(Legend)s?anntzer commentedon Mar 8, 2018
I decided I have better battles to fight right now (but I'd vote yes in response to your specific question).
github-actions commentedon Apr 29, 2023
This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!