Skip to content

Improve doc for data kwarg. #15776

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
Dec 10, 2019
Merged

Improve doc for data kwarg. #15776

merged 1 commit into from
Dec 10, 2019

Conversation

anntzer
Copy link
Contributor

@anntzer anntzer commented Nov 26, 2019

PR Summary

Previous doc for e.g. scatter:

    .. note::
        In addition to the above described arguments, this function can take a
        **data** keyword argument. If such a **data** argument is given, the
        following arguments are replaced by **data[<arg>]**:
    
        * All arguments with the following names: 'c', 'color', 'edgecolors', 'facecolor', 'facecolors', 'linewidths', 's', 'x', 'y'.

with this patch:

    .. note::
        In addition to the above described arguments, this function can take
        a *data* keyword argument. If such a *data* argument is given,
        each of the following arguments, if it is a string, is
        replaced by ``data[<arg>]`` (unless this raises an exception):
        'y', 'color', 'edgecolors', 'x', 'linewidths', 'facecolor', 's', 'facecolors', 'c'.

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

@timhoffm
Copy link
Member

timhoffm commented Nov 26, 2019 •
edited
Loading

What about

    .. note::
        In addition to the above described arguments, this function can take
        a *data* keyword argument. If such a *data* argument is given,
        each of the following arguments accept a string ``s`` which is
        interpreted as ``data[s]``:

        - *y*
        - *color*
        - *edgecolors*
        - *x*
        - *linewidths*
        - *facecolor*
        - *s*
        - *facecolors*
        - *c*

At some point, I would like to inject a data entry into the Parameters text so that we can remove the first sentence as well.

@anntzer
Copy link
Contributor Author

anntzer commented Nov 26, 2019

I switched to using asterisks, but kept listing everything on a single line -- a bullet list seems a bit too... expansive?

@anntzer anntzer force-pushed the datakwargdoc branch 2 times, most recently from d3900e2 to 855e917 Compare November 26, 2019 14:27
timhoffm
timhoffm reviewed Nov 28, 2019
View reviewed changes
Copy link
Member

@timhoffm timhoffm left a comment

Choose a reason for hiding this comment

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

Won't fight over the bullet list, even though I believe it's easier to scan than a comma separated list.

timhoffm
timhoffm reviewed Nov 28, 2019
View reviewed changes
@anntzer
Copy link
Contributor Author

anntzer commented Dec 10, 2019

:s/each/every per @story645's suggestion

@story645 story645 merged commit fb0e229 into matplotlib:master Dec 10, 2019
@anntzer anntzer deleted the datakwargdoc branch December 10, 2019 23:28
@tacaswell tacaswell added this to the v3.3.0 milestone Dec 11, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@timhoffm timhoffm timhoffm approved these changes

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

Successfully merging this pull request may close these issues.
4 participants
@anntzer @timhoffm @tacaswell @story645