napoleon: support "Keyword-only arguments" section

[mivade]

It's generally useful to explicitly call out keyword-only arguments in Python 3. Currently when using the numpydoc format, I might have a docstring containing something like

def foo(*, what):
    """Do something then do something else.

    Keyword-only arguments
    -------------------------
    what: str
        What else to do.

    """

Instead of titling the section as expected, it ends up looking something like:

• arguments (Keyword-only) –
• ---------------------- –
• what - what else to do

[AA-Turner]

cc @lucascolley I'd prefer not to diverge from numpydoc -- is this something you'd consider upstream? Otherwise we will reject this proposal.

A

[lucascolley]

I think it seems unlikely. A contributor said:

Personal opinion: keyword-only (and positional-only) are just syntactic usage aspects. They don't carry information for understanding the function and its parameters. I therefore propose that it's sufficient to let the user infer the usage from the signature and would not document that aspect in the parameters section at all.

And that got 2 +1s from numpydoc devs. I'm inclined to agree - with introducing a second source of truth, I would worry about them diverging and causing more confusion than help.

I think there is an argument to be made that spelling out keyword-only would be helpful for users who haven't seen the * syntax before, though. But maybe that isn't so hard to figure out after hitting a few "too many positional argument" errors.

[AA-Turner]

Closing per rationale. Will revisit should numpydoc alter their view.

A