[Doc]: Document color in a consistent way, including link #24859
Comments
|
I kinda like how to RGBA spells it out as Matplotlib Color since we don't have a "color" type & I sometimes have been linking out to the tutorials/referenced in the description. Something like
It's a little bit wordier, but is also more explicit that there isn't a specific matplotlib color type. |
|
If we wanted to have a color type to link to, I wonder if we could make use of a typing alias, e.g. Color = typing.Union[str, typing.Tuple[float]]ETA: I assume we would eventually want something like that for the type annotations work anyway. |
So there was a GSOD proposing something like that a few years back (link) b/c it makes it easier to document a lot of the parameters if we formalize them as types (and it gives us a logical place to put validation logic) - here's an example for the join and capstyles #18544 & I think there's probably some intersection w/ @ksunden 's work. I'm just worrying that documenting it in this way right now will imply that we already have an explicit "color" type. |
|
Python typing isn't really sufficient for documenting the color parameter though, because, it doesn't tell you what strings (or floats, although that's easier) are valid. |
|
I was thinking that, once you have your (alias) type, you could hang a docstring off it with |
|
On a general note: The topic is quite large. It covers at least validation, conversion, normalization (we have no standard how to return colors - often rgb(a) but sometimes also whatever was passed in) and documentation. There has been the idea that an actual Color class would be useful to consolidate these topics. It has to be seen whether that's only for internal use or whether that would be exposed. It's also to be seen whether one wouldwant to document in the docstring of such class or somewhere else. There are also similar cases for other types, e.g. JoinStyle, CapStyle (#18544) and LineStyle (#18664). Since this is quite a lot, the pragmatic approach is to do this incrementally. Turning color into links similar to the proposal is a good first step. However, I recommend creating a label and using or (if the section title is not "color") That's shorter than the tutorial reference and easier to change the target. (The colors tutorial is currently the right target - except that it is not a tutorial. It a reference page, for which we currently do not have a good place in the docs, see also #24746 (comment)). |
The role is intended to be used for type references in
docstrings like
```
Parameters
----------
color : :mpltype:`color`
```
It is easily extendable to other types.
The naming `mpltype` was a quick choice. I'm open to better names.
This PR contains one example usage in `widgets.Button` so that one can
see the effect in the built docs. Systematic application
throughout the codebase should be deferred to a separate PR.
Closes matplotlib#24859.
Formalizes matplotlib#27164.
The role is intended to be used for type references in
docstrings like
```
Parameters
----------
color : :mpltype:`color`
```
It is easily extendable to other types.
The naming `mpltype` was a quick choice. I'm open to better names.
This PR contains one example usage in `widgets.Button` so that one can
see the effect in the built docs. Systematic application
throughout the codebase should be deferred to a separate PR.
Closes matplotlib#24859.
Formalizes matplotlib#27164.
Documentation Link
No response
Problem
Matplotlib has a rather flexible color concept, see https://matplotlib.org/stable/tutorials/colors/colors.html
In the documentation, the type of color arguments is often, but not always, listed as "color", although there are limited hints what this actually means.
Suggested improvement
Link the type
colorto the page above (is there a better one?). Update other types (likestr) to becolor.These are the ones I found through a simple grep.
The text was updated successfully, but these errors were encountered: