Update legend loc default value in docstring #11517
Conversation
lib/matplotlib/legend.py
Outdated
| @@ -111,7 +111,7 @@ def _update_bbox_to_anchor(self, loc_in_canvas): | |||
|
|
|||
|
|
|||
| _legend_kw_doc = ''' | |||
| loc : int or string or pair of floats, default: 'upper right' | |||
| loc : int or string or pair of floats, default: :rc:`legend.loc` | |||
There was a problem hiding this comment.
Can you please also state the default rc value like this:
default: :rc:`legend.loc` = 'best'
There was a problem hiding this comment.
Ah, didn't read your text completely.
We would like to add the rc default values in the future (there's a pending PR #10714 for this)
See section rcParams in https://10714-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/devel/documenting_mpl.html?highlight=documenting#writing-docstrings.
It's true that this is a bit more involved in the case of legend. I think your propoal
default: :rc:`legend.loc` ('best' for axes, 'upper right' for figures)
is reasonable.
I wouldn't want a default issueing a warning that it will be changed. This is rather confusing. Of course, the best way, would be to have 'best' also for figures. Since we don't have that for now, the different defaults make sense.
There was a problem hiding this comment.
Great thanks for letting me know about that, including the default param value is a welcome change, looking forward!
I wasn't sure which line break strategy to use for the parentheses here. I went with the same approach as in figure.py lines 695-696, as this was the only other occurrence of a line breaking default: I could find. It does make the line quite long compared to other lines in the docstring, so I can add a line break instead if you prefer. I just need advice on how much I should indent the line after the break.
|
Thanks @joelostblom ! |
…n-v2.2.x Backport PR #11517 on branch v2.2.x
PR Summary
The default value for legends'
locparameter is stated to beupper rightin the docstring, but it is actually read from the rcParamlegend.loc. Only when the parent of the legend is a figure and the default rcParam is'best', this is overwritten with'upper right'since automated legend positioning is not implemented for figures. This can be confusing, as indicated by the two last comments here.Ideally, I would like to add to this PR and make the difference between legends of figures and axes objects explicit, e.g.
default: :rc:`legend.loc` ('best' for axes, 'upper right' for figures), but I noticed elsewhere in the documentation that the default parameter values are not explicitly stated, so I didn't want suggest an inconsistent change here.An alternative would be to not silently change the default value for figures, but instead raise the same warning as when
loc='best'is specified manually, also when the rcParam is set to'best'(so just remove lines 485-486).PR Checklist
Has Pytest style unit testsNew features are documented, with examples if plot relatedAdded 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