-
-
Notifications
You must be signed in to change notification settings - Fork 7.6k
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.
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
DOC: Best practice when to use ax.set_thing(foo) vs ax.set(thing=foo) #28693
Comments
Proposal:Use Our docs, have higher bar on being understandable and instructive. I therefore would be a bit more specific. As rules of thumb for the matplotlib docs:
|
I agree that For the docs/examples, I think @timhoffm and @story645 both make good arguments in opposing directions and I do not know how to choose between them! So I would vote for not codifying this but instead leave it up to individual authors and their reviewers. This also fits my general preference for not making the contributors’ guide any larger than it needs to be. |
My preference for consistency in the docs means I'm okay w/ the decision not going in my favor, and i think adding this to an entry in the style guide would be OK? I see that as sorta the doc equivalent to the PR guidelines, more for maintainers than contributors, but also means then we don't have long discussions about it on every PR. I also agree w/ you very much that really it's so very case dependent. I think Tim's first bullet is a good compromise:
Anything more than about 2 properties and the
I love highlighting that set works for all the things & is the wonderful all the things function folks want. |
Documentation Link
No response
Problem
Inspired through the discussion at #28677 (comment): Through #20569 we have made
Artist.set()
more useable. In particular, we have started toAxes.set()
in some places in the documentation.We currently do not have a best practice when to
ax.set_thing(foo)
vsax.set(thing=foo)
.Suggested improvement
We should have a best practive when to use what that we document, teach and use in our docs.
There was a loose discussion at https://github.com/matplotlib/ProjectManagement/blob/b9b0a56cb7b329c3c2adfac77a84975f70868e24/meeting_notes/2021/q2.md#do-we-want-to-soup-up-and-advertise-objset-more, but no definitive solution.
General observations:
set_thing()
:set(thing=...)
one has to go toset()
and follow the link for the specific keyword).set(thing=...)
:ax.set_<TAB>
andax.set(<TAB>
)set(**kwargs)
signatures)set_thing
was mostly used and advertizedPlease add if you have additional points.
I'll stop here without suggesting a solution to keep the discussion unbiased. Suggestions for solution should be posted as separte comments.
The text was updated successfully, but these errors were encountered: