Doc: highlight rcparams #15115
Doc: highlight rcparams #15115
Conversation
|
flake8 failure is real, but other than that I do like the idea a lot. |
a9730c2 to
bd642cf
Compare
bd642cf to
24cdef4
Compare
|
Actually, we could in addition directly include the default value in the rc role output:
What do you think? |
doc/sphinxext/custom_roles.py
Outdated
|
|
||
| param = rcParamsDefault.get(text) | ||
| if isinstance(param, str): | ||
| txt = f' : "{param}"' |
There was a problem hiding this comment.
- no space before the colon? (or use "=")
- you can probably get away with
{param!r}(aka{repr(param)}) which will give you the quotes for strings, instead of having to special case them.
|
The default may be a bit confusing? Is it obvious this is marplotlibs default? Not sure how to improve it though. Maybe brackets? Otherwise this seems great |
|
Also, who ever merges this, please make sure I notice and re-build the 3.1.x docs. |
|
Options:
Personally I don't really care too much, so if anyone has a good argument for or against one or several of those... |
|
preference for "=" and ":" (without space before the colon), but anything is an improvement! |
efd3505 to
75ce592
Compare
|
Ok, went for "=" now, because that actually gives valid python code:
|
|
This is great! 🎉.
If I was nitpicky, that is a bit misleading. Assignment is not what we want to express; and thinking of this, I have a tiny doubt if people would misunderstand the "=". Anyway, "=" is what we are recommending in the documentation guide, so it's fine. But the documentation guide should be updated to reflect the new behavior. |
|
I would do something like (def.=xx) but maybe that’s too wordy |
|
If we want to be really clear |
|
Dflt? |
|
Hmmm, no. Readability counts also for the docs. We wouldn't use dflt as variable name. Why start saving letters in the documentation, which is allowed to be textually more verbose anyway.? |
|
I like |
…115-on-v3.1.x Backport PR #15115 on branch v3.1.x (Doc: highlight rcparams)
…115-on-v3.1.1-doc Backport PR #15115 on branch v3.1.1-doc (Doc: highlight rcparams)
|
Looking at the changes in #15230, the fact that or These will become: or This implies that you should set the rcParam to its default value, but those sentence often just mean set it to anything. |
PR Summary
Many of the function parameters default to
None, in which case the value from an rc parameter is taken. The custom:rc:role allows to link to the template, but it's always been bothering me that you then have to scroll through that complete file to locate the parameter you want to know the default of.This PR will highlight the parameter in question, such that it is easier to locate.
I.e. if you click on a parameter, eg.
you will now be directed to
and then scrolling down the file, the parameter in question is highlighted like this:
PR Checklist