I have an implementation of a custom :rc: role so that one can write

:rc:`lines.linewidth`

and get this mapped to, well, whatever we want. The nice thing is that roles can be in the postfix position too, so we could even have a construct such as

the `lines.linewidth`:rcparam:

which seems very readable and lightweight in plain text.

The PR depends on #9708 though so I'll wait for that PR to be merged first.

Edit: actually not that hard to split out, see #10226.

For array(-like) parameter type descriptions we should probably use something close-ish to numpy's current effort (python/typing#516 and stuff linked therein).
For other parameters we should use typing-style annotations. There was some concerns that sphinx may or may not be able to support e.g. List[~.Axes] but if that's the case we should try to fix this on sphinx's side...

Note: handling of parameter lists updated: #10280

Also, I think I prefer float to scalar, even though it is a slight abuse of language to make it mean "float-or-int" (I guess if you want to be really pedantic we usually mean https://docs.python.org/3/library/numbers.html#numbers.Real anyways...).

👍 all of these seem eminently reasonable.

I will recheck what other scientific libraries are using. It makes sense to try and use a common language. Then I will provide a pull request.

Proposal for array-like types

There is no strict consensus among or even within other scientific libraries (checked numpy, scipy, pandas). The prevalent form is a variant of "array-like". So, I propose

Use array-like for homogeneous sequences, which could typically be a numpy.array.

If required, this can be amended with dimensions array-like(N,) / array-like(M, N).

float is the implicit default dtype. If required, an alternative type may be specified: array-like of int.

I have continued to edit some docstrings (figure and pyplot) and I believe that after some confusion it is quite clear how to write. A few question though.

Are there any convention for how to write True, False and None? I believe that they are written in all possibles ways in the docstrings. I think doing nothing special works well but single back ticks gets a link to the python documentation and looks good.

How to write example code in the docstrings? With .. code:: or with >>>? I believe that the first one is often the best but including the result is better done in the last one (but that is probably not that common in matplotlib examples).

Things that have been confusing to me are if the markups, :class:, 'func: etc, should be used or not. I realize now that a section in the documentation where about those but I thought markups there meant some other markup.

I also got confused that back ticks should not be used in the See Also section.

Personally, I currently use *True* etc. I find it appealing to visually offset these from regular text. I don't see the point in back-linking to the python documentation using single bac kticks. Also the link color makes these too visually present. In the rendered html, the <code> effect of double back ticks would be optimal. But I find double back ticks too distracting in the rst code ( ``True``). Just personal preference. I don't think we have a definitive rule for that, currently.

... code:: and >>> are both used. It depends a bit if you rather have a single line with input and output or a multi-line code block. For ... code:: you should usually use the abbreviated form of just putting :: at the end of a paragraph (unless you need to specify ... code:: attributes.

:class: etc should be left out where possible to improve readability (i.e. where there is not an ambiguity in the name).

I'm not quite sure right now about See Also I assume that this is something managed wihin numpydoc and thus works without quotes.

Ok, some other comments in regard to kwargs and what to link to.

I found it frustrating that the Axes kwargs are not included in the natural place in the documentation. Wouldn't it be better to just make some kind of hack to get them into the documentation compared to waiting for someone writing a good solution?

I also looked at the Axes string that can be used in dedent_interpd. sharex, and sharey where not included, probably because they don't have a setter. Easy to be confused though if not all possible keywords are included in that string.

How to link to the documentation when subclasses are involved? axes are often not axes.Base classes. I believe that the _AxesBase class is not included in the documentation and cant be linked to. The classes and functions in axes._subplots cant be linked to for same reason, are they not public even though they are the result type of several functions? I guess that the general subplot class cant be linked to because it is dynamic but the Subplot class should exist.

What about including _AxesBase in the documentation and maybe make it public?
edit: I see now that all axes I know of have axes.Axes as parent so probably no need to _AxesBase.

What is the best way to look at very long docstrings?

edit: Are there really any reason to include the kwargs list in methods? For example in plot
plot

The table is one click away in the docs and the table often looks bad in a shell and makes the docstring much longer.

I cannot really say something on the Axes topic. Didn’t have time to look into it yet.

What is the best way to look at very long docstrings?

Not sure what you mean with that. HTML page?

The kwarg tables are debatable. They’ve been around for a long time. On the plus side, it’s more obvious which values are supported. With a link, you’d still have to follow the link and find the relevant part of the target docstring (the link goes to the top of the docstring not to the list). That’s not impossible, but a distraction. On the shell (or in jupyter notebooks) you don’t have the link and it’s difficulty get the information there. Therefore, I’m +0.5 on keeping the kwarg lists.

Most of the recommendation have been incorporated into the documentation guide. Currently, I don't see the need for further work.