The actual implementation needs to use kwargs as long as we maintain Py2 compat (because otherwise the arguments become positional-or-keyword, which doesn't make much sense). The doc can write the "actual" signature in the first line (http://www.sphinx-doc.org/en/stable/ext/autodoc.html#confval-autodoc_docstring_signature).

Per standard policy I would throw a deprecation warning in 2.2 for unhandled arguments. This way, the next release (which should hopefully be 3 and Py3 only...) can just switch to using normal kw-only arguments.

I think its OK-ish for "See Also" to link to other documents or packages so long as the docs don't require that See Also... I think of it as a "reference" section.

See #4829 for the meaning of the @_preprocess_data decorator, though I admit I still don't understand it. But I think it requires the args in that form?

@anntzer the positional-or-keyword issue is already present in the current implementation (stem(y, linefmt='g') vs. stem(y, 'g')) and is explicitly handled in the code. This wouldn't change with explicit keywords.

@jklymak @_preprocess_data can also work with explicit args and kwargs. See e.g. Axes.pie

For now, I've resorted to auto_docstring_signature. But that ignores @_preprocess_data, which I have to add manually. I feel that adding more magic is the wrong direction.

Ah, I see. Unless there's a (likely...) dragon in the rabbit hole, I'm +1 to just move the kwargs into the signature then.

Note: auto_docstring_signature is not supported/filtered out in pyplot._setup_pyplot_info_docstrings(). I.e. the signature would be part of the overview in the stem description on https://matplotlib.org/api/pyplot_summary.html.

If we really need this mechanism some time, pyplot._setup_pyplot_info_docstrings() must obtain the capability to strip the signature from the docstring.

For the present case, I will revert the docstring signature and try to pursue explicit keywords.

Ok, found the dragon in the rabbit hole: The issue is having a variable number of positional-only arguments (y or x, y) and some additional arguments that can be positional or keyword (the *fmt args).

In particular, simultaneously satisfying the following call patterns is not possible with explicit signatures in Python 2:

stem(y, linefmt='--')
stem(y, '--')
stem(x, y)

Python 3 would be fine with

stem(*args, linefmt=None, markerfmt=None, basefmt=None, bottom=0, label=None)

This makes the *fmts keyword only. The internal logic in the mehod can check if they are set or not, and try to obtain them from *args otherwise.

Python 2 requires *args to be behind explicit keywords:

stem(linefmt=None, markerfmt=None, basefmt=None, bottom=0, label=None, *args)

Then, I cannot stem(y, linefmt='--') because Python would try to bind both arguments to linefmt.

I'm reverting to the generic signature, since we currently cannot do better without breaking the API.

Closing as "good enough".