Skip to content

Docstring interpolation does not work correctly for indented insertions #10161

Closed as not planned

Description

@timhoffm

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?

Activity

  1. anntzer commented on Jan 4, 2018

    @anntzer
    Contributor

    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)

  2. anntzer commented on Jan 5, 2018

    @anntzer
    Contributor

    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...

  3. timhoffm commented on Feb 1, 2018

    @timhoffm
    MemberAuthor

    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.

    Other Parameters
    ----------------
    %(Line2D)s
    

    would become

    Other Parameters
    ----------------
    agg_filter
        a filter function ...
    alpha
        float (0.0 transparent to 1.0 opaque)
    ...
    

    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.

  4. jklymak commented on Mar 8, 2018

    @jklymak
    Member

    Where are we w/ this? legend has three identical docstrings, and I'd sure like to be able to use docstring interpolation...

  5. anntzer commented on Mar 8, 2018

    @anntzer
    Contributor

    You may be interested in anntzer@0f72aa4 which was a start at converting to the new interpolation system I proposed above.

  6. jklymak commented on Mar 8, 2018

    @jklymak
    Member

    Very interested!

  7. jklymak commented on Mar 8, 2018

    @jklymak
    Member

    But in the meantime can I use %(Legend)s?

  8. anntzer commented on Mar 8, 2018

    @anntzer
    Contributor

    I decided I have better battles to fight right now (but I'd vote yes in response to your specific question).

  9. github-actions commented on Apr 29, 2023

    @github-actions

    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!

  10. added
    status: closed as inactiveIssues closed by the "Stale" Github Action. Please comment on any you think should still be open.
    on May 30, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Documentationstatus: closed as inactiveIssues closed by the "Stale" Github Action. Please comment on any you think should still be open.status: inactiveMarked by the “Stale” Github Action

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions