Reorder kwonly kwargs in Colorbar & related docs.#29652
Reorder kwonly kwargs in Colorbar & related docs.#29652timhoffm merged 1 commit intomatplotlib:mainfrom
Conversation
Move "redundant" kwargs (cmap/norm can be specified via mappable;
orientation/ticklocation can be specified via location) to the end of
the kwarg list and under an "Other Parameters" section.
Also remove mention of Normalize(clip=False);
imshow(rand(10, 10),
cmap=mpl.colormaps["viridis"].with_extremes(under="w", over="k"))
colorbar(extend="both")
seems enough to have over/under colors show up, i.e. no need to fiddle
with the clip parameter.
| Other Parameters | ||
| ---------------- |
There was a problem hiding this comment.
It seems like numpydoc is placing the Attributes section between Parameters and Other Parameters, which I find quite confusing.
I propose not use Other Parameters then here.
Edit: This is an intentional change in numpydoc 1.8 (numpy/numpydoc#571), though I'm not clear whether this effect was considered.
We can work around this by moving the parameters to the __init__ docstring, because that seems to be appended below the class docstring, see e.g. https://matplotlib.org/devdocs/api/widgets_api.html#matplotlib.widgets.Button. In a quick check, this seems to be a pattern we generally use.
timhoffm
left a comment
There was a problem hiding this comment.
I'll merge this as is and do a follow-up to move the parameters to the init docstring. That's logically simpler than reordering and moving at the same time.
This prevents numpydoc from inserting Attributes between Parameters and Other Parameters see https://github .com/matplotlib/pull/29652#pullrequestreview-2634087106. It's also a pattern we generally use.
…652-on-v3.10.x Backport PR #29652 on branch v3.10.x (Reorder kwonly kwargs in Colorbar & related docs.)
Move "redundant" kwargs (cmap/norm can be specified via mappable; orientation/ticklocation can be specified via location) to the end of the kwarg list and under an "Other Parameters" section.
Also remove mention of Normalize(clip=False);
seems enough to have over/under colors show up, i.e. no need to fiddle with the clip parameter.
PR summary
PR checklist