8000 Improve properties formatting in interpolated docstrings. by anntzer · Pull Request #14035 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

Improve properties formatting in interpolated docstrings. #14035

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 1 commit into from
May 26, 2019
Merged

Improve properties formatting in interpolated docstrings. #14035

merged 1 commit into from
May 26, 2019

Conversation

anntzer
Copy link
Contributor
@anntzer anntzer commented Apr 25, 2019

This makes docstring interpolation a bit less sensitive to the indent
where the inserted string goes. For example, the docstring of
add_subplot goes from

    **kwargs
        This method also takes the keyword arguments for
        the returned axes base class. The keyword arguments for the
        rectilinear base class `~.axes.Axes` can be found in
        the following table but there might also be other keyword
        arguments if another projection is used.
          adjustable: {'box', 'datalim'}
      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 or None
      ...

to

    **kwargs
        This method also takes the keyword arguments for
        the returned axes base class. The keyword arguments for the
        rectilinear base class `~.axes.Axes` can be found in
        the following table but there might also be other keyword
        arguments if another projection is used.

        Properties:
        adjustable: {'box', 'datalim'}
        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 or None

Note that this does not affect sphinx rendering as that uses
pprint_setters_rest.

Note that whether the properties list is indented relative to the
"Properties" header depends on the indent where the inserted string goes
(lines starting from the second one are always indented by 4
characters (8 looks like too much), but I think it's still an
(incremental) improvement.

Also make sure that the property list is preceded by a newline.

PR Summary

PR Checklist

  • Has Pytest style unit tests
  • Code is Flake 8 compliant
  • New features are documented, with examples if plot related
  • Documentation is sphinx and numpydoc compliant
  • Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
  • Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

efiring
efiring approved these changes May 26, 2019
View reviewed changes
Copy link
Member
@efiring efiring left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs rebase, then I will merge it.

@anntzer
Improve properties formatting in interpolated docstrings.
77a9633 
This makes docstring interpolation a bit less sensitive to the indent
where the inserted string goes.  For example, the docstring of
`add_subplot` goes from

```
    **kwargs
        This method also takes the keyword arguments for
        the returned axes base class. The keyword arguments for the
        rectilinear base class `~.axes.Axes` can be found in
        the following table but there might also be other keyword
        arguments if another projection is used.
          adjustable: {'box', 'datalim'}
      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 or None
      ...
```
to
```
    **kwargs
        This method also takes the keyword arguments for
        the returned axes base class. The keyword arguments for the
        rectilinear base class `~.axes.Axes` can be found in
        the following table but there might also be other keyword
        arguments if another projection is used.

        Properties:
        adjustable: {'box', 'datalim'}
        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 or None
```
Note that this does not affect sphinx rendering as that uses
pprint_setters_rest.

Note that whether the properties list is indented relative to the
"Properties" header depends on the indent where the inserted string goes
(lines starting from the second one are *always* indented by 4
characters (8 looks like too much), but I think it's still an
(incremental) improvement.

Also make sure that the property list is preceded by a newline.
@anntzer anntzer force-pushed the < 8000 span class="commit-ref user-select-contain"> interpd branch from 93adce9 to 77a9633 Compare May 26, 2019 06:49
@anntzer
Copy link
Contributor Author
anntzer commented May 26, 2019

done

@timhoffm timhoffm merged commit 6f1ffeb into matplotlib:master May 26, 2019
@anntzer anntzer deleted the interpd branch May 26, 2019 11:05
@QuLogic QuLogic added this to the v3.2.0 milestone Jul 24, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@efiring efiring efiring approved these changes

@timhoffm timhoffm timhoffm approved these changes

Assignees
No one assigned
Labels
Documentation
Projects
None yet
Milestone
v3.2.0
Development

Successfully merging this pull request may close these issues.
5 participants
@anntzer @efiring @timhoffm @QuLogic @dstansby
0