The biggest downside of this is that reading the docstrings via ? in IPython will be a bit more confusing, but I think it is still reasonably clear.

Hah, now you're going to be mad about that legend docstring check I snuck in.... If you change one, you have to change all three identically. Though I won't throw a fit if you remove the test.

bah, I guess the test did its job...

Yeah, but I'm not convinced this is so efficient. I'd still like to use something like the doc interpolation for things like this, assuming enough tools support them.

I have a pretty good idea on how to make interpolation work robustly, but (you won't believe me) also a life outside of mpl these days...
If anyone wants to pick it up the proof of concept is at https://github.com/anntzer/structured-docstrings but under "interpolated docstrings" (the older "structured docstrings" idea was rejected as too complicated -- not totally convinced, but that's a reasonable argument): it's basically using {} formats; picking values from the caller's globals (so no need to maintain a global interpd and use interpd.update, it's just a free function; if stack walking looks too weird one can instead ask the caller to explicitly pass globals() -- not a big deal IMO); checking what is the indentation of the {} (which must only be preceded by whitespace) and interpolating the requested value with the correct indentation based on that; and relying on a custom converter to support kwdoc()-type effects.

Oh, cool: cross-ref to #9414 But I like that syntax and the stricture that it has to stand on its own on the line. I don't buy the argument that our somewhat unique doc needs can't use a few non-standard tools so long as they are robust. pinging @timhoffm as I know he has been very interested in the state of the documentation.

Can we just wait until we can use fstrings for the docs?

I have a pretty good idea on how to make interpolation work robustly, but (you won't believe me) also a life outside of mpl these days...

Good!

When can we use f-strings? That seems like it’ll solve a lot of problems. But it’s a 3.6 feature right? Are we likely to drop <3.6 support at some point?

f-strings are not recognized as docstrings... (which probably makes sense)

>>> def f():
...     f"foo"
... 
>>> f.__doc__
>>> 

IIRC the plan is to make mpl 3 require py 3.6 (and there was much rejoicing).

This looks cool. I'll give the folks who are interested in documentation a day or two to Approve before merging.

I'm uneasy with the effect this has on plain-text readability; it seems like a possible net gain only if it makes a big difference on the Sphinx side. If I understand correctly, this is presently not the case.

It does make writing a docstring slightly simpler, which is good, of course.

Basically the problem is that there is no possible link target yet for these elements (no unified doc on the rcParams). I don't mind waiting for a proper rc docs be merged first (other than by the usual rebase churn).

Because roles can also be in postfix position (with no change), an early version of this patch used :rc: as role and one could write

the `lines.linewidth`:rc: is etc.

which may or may not considered an improvement.

In general I consider @efiring 's concern a blocking issue...

As mentioned above I don't have a particularly urgent need to get this merged.

Readability is good, but is

:rcparam:`figure.boo`

harder to read than

`rcParam[figure.boo]`

let alone

``figure.boo`` :data:`rcParam<matplotlib.rcParams>`

The second does have the advantage of being a code snippet.

That's the only point: code snippet versus something that has to be interpreted. As I said, I'm just a little uneasy--I'm not adamantly opposed, and maybe won't end up being opposed at all.

Veering off the specific topic of this PR:
In the evolution of our documentation and docstrings, I'm not always sure we are making good tradeoffs. Some of the numpydoc reformatting, for example, seems to be making docstrings longer and more verbose, which harms usability, especially when viewed as raw text in ipython or in an editor.

Putting in sphinx markup involves a tradeoff, which needs to be evaluated on a case-by-case basis. For example, putting in the markup required to generate a link for a function can be worth the raw-text clutter once in a docstring; but if the docstring needs to use the name of the function more than once, there is no need to repeat the clutter. A single reference with a link is enough.

+1 I think, the role is really helpful.

Code snippet vs. something has to be interpreted
Currently, we've only used a code snipped like rcParams['animation.codec'] twice in the docstring. Most of the times its another somehow descripive expression as I've listed in #10225. Also, a real code snippet is quite verbose in plain text:

``rcParams['figure.boo']``

IMO worse than just

:rcparam:`figure.boo`

if there are concerns that this is not intelligible in plain text, one could change the role name to rcParams:

:rcParams:`figure.boo`

OT: Evolution of docstrings

From http://www.sphinx-doc.org/en/stable/ext/napoleon.html:

NumPy style tends to require more vertical space, whereas Google style tends to use more horizontal space. Google style tends to be easier to read for short and simple docstrings, whereas NumPy style tends be easier to read for long and in-depth docstrings.

Yes, it's getting a bit longer. But since many docstrings are long anyway. it's better to add a clear structure at the cost of even a bit more length.

If we use the short form `.Lines2D` for cross referencing, the overhead is not too bad. Nevertheless, I agree that you do not have to cross-reference multiple occurences of a name within a given context.

If there is more to discuss OT, #10225 might be a better place.

@efiring OK to merge? Its not that hard to search and replace to get rid of it again if we decide its not good....

There are two questions that need to be decided before it should be merged:

1. Is adding a new role for this a good idea?
2. If so, what should it be called?

Modifying what the role does is relatively easy after this PR, creating the role, is merged; changing the name, or removing it entirely, is not. And question 2, naming, really does matter.

I'm willing to go along with a "yes" for the first question.
For the second, the candidates seem to be:

1. rcparam
2. rcParams
3. rc

I think (2) is better than (1) because it matches the relevant array name--maybe it is not a great name, but we are stuck with it.
I lean towards (3) as the best because

• it is concise
• it is generic, matching rc(), rc_context, rcdefaults, rcParams, and rcParamsDefault, all of which lurk in the pyplot namespace, waiting to confuse the poor user.

Alternatives? Contrary arguments? I'm open to all.

fwiw the original version I wrote used rc (which I still prefer); I only changed it to rcparam because some suggested that rc may be too obscure. But I sort of agree with @efiring that once we're at rcparam we may as well use rcParams...

Who knows what I said two or three days ago, but I'm happy w/ any of these forms....

I'm fine with either rc or rcParams.

I also am fine with rc or rcParams. I lean towards rc because there's no ambiguity in capitalization, whereas I see myself trying to remember: "Is it rcparams or rcParams?"

I think role names are actually case insensitive (but can't find the ref now and that should be checked again).

Summarizing the opinions on naming:

• rc: 4 votes
• rc or rcParams: 2 votes (roles are case insensitive, so the upper case P would just be convention)
• rcparam: not a favorite by anybody

No very strong opinions either way, but there's a clear tendency for rc. So this should be updated.

fixed