DOC: scales - built in options and custom scale usefulness #29404
Conversation
lib/matplotlib/axis.py
Outdated
| value : {"linear", "log", "symlog", "logit", ...} or `.ScaleBase` | ||
| The axis scale type to apply. | ||
| value : str or `.ScaleBase` | ||
| The axis scale type to apply. Supported string values are "linear", "log", |
There was a problem hiding this comment.
Can you somehow integrate a link to https://matplotlib.org/devdocs/api/scale_api.html (maybe directly to the table (?) by adding a rst label before the table). The strings alone give a rough idea, but the link would give the ability to read up un what they mean and which kwargs are supported. You then may or may not leave out the explicit bullet list of classes under kwargs. Alternatively, create a table/bullet list (str name: class) under the value attribute to make the connection here, but still link out for additional context.
There was a problem hiding this comment.
I like the idea of just linking to the table (which I didn't know was there!) Having the information in one place means we don't have to worry about keeping two versions in sync.
|
|
||
| If you do not need any of the above, then you probably don't need to use this | ||
| verbose method, and instead can use `~.scale.FuncScale` and the ``'function'`` | ||
| option of `~.Axes.set_xscale` and `~.Axes.set_yscale`. See the last example in |
There was a problem hiding this comment.
Additional note: I think we should make the FuncScale case more prominent. Not only as "last example in ...". Either as a top level example in parallel to this example, or by making two subsections in this example.
There was a problem hiding this comment.
I have no objection to this, but also not the bandwidth right now.
| @@ -3,7 +3,9 @@ | |||
|
|
|||
| The mapping is implemented through `.Transform` subclasses. | |||
|
|
|||
| The following scales are builtin: | |||
| The following scales are built-in: | |||
There was a problem hiding this comment.
Merriam-Webster says this is hyphenated, though we seem to have both ways all over the docs...
There was a problem hiding this comment.
ChatGPT says:
The correct spelling depends on how the term is used in a sentence:
-
"Built-in" (with a hyphen) is an adjective. It is used to describe something that is an integral or permanent part of something else.
- Example: "The phone has a built-in camera."
-
"Builtin" (no hyphen) is not a standard English word, but it is sometimes used as a term in programming or technical contexts, especially in filenames, identifiers, or codebases. For instance, Python has "builtin functions," though even here, "built-in" is more widely accepted in official documentation.
To summarize:
- For general usage, "built-in" with a hyphen is correct.
- For programming or technical contexts, check the convention of the specific language or framework being used.
…om scale usefulness
…404-on-v3.10.x Backport PR #29404 on branch v3.10.x (DOC: scales - built in options and custom scale usefulness)
PR summary
Today I spent way too long trying to wrap my head around why someone might write a custom scale. I have updated the example with what I think I have understood. Also updated the
set_[xy]scaledocstring as it was missing some built-in options, and I think we can be clearer about what happens to**kwargs.PR checklist