Support keyword args and yields sections

[pawamoy]

Closes #324 and #205

[pawamoy]

CI needs #330 to pass.

[oprypin]

Actually... I don't understand the purpose behind a "keyword args" section. The descriptions of all parameters can be within one section, why should they be separated?
The actual viability of passing arguments should be visible from the function's signature.

[pawamoy]

The purpose of the Keyword Argument section is to be able to document arguments that can be passed through **kwargs, and to enjoy the same formatting as for regular Arguments sections.

Consider this:

def function(a, b, **kwargs):
    c = kwargs.pop("c")
    d = kwargs.pop("d")
    # use a, b, c, d

You can document a, b, and **kwargs in the Arguments section, but not c and d directly, as they are not part of the signature (linters not happy). You could document them in the **kwargs description, but you'd have to use plain Markdown formatting for anything a bit elaborate. Instead, with a Keyword Arguments section, you can document c and d just like any other argument:

Keyword Arguments:
    c (int): Description.
    d (list[str] | None): Description

[oprypin]

Wait, I thought that Python has eliminated all cases where you'd have to rely on **kwargs to serve particularly-named keyword-only arguments. Wouldn't it be good to just hope that the last usages of this will die out soon and encourage writing the arguments directly?

def function(a, b, *, c, d):

[pawamoy]

You have good arguments as always @oprypin 🙂
I don't know if it's reasonable to expect that this use of **kwargs will disappear (its only use apart from swallowing unwanted arguments?). Support for this was explicitly requested by users 😕

[oprypin]

Well, if supporting this never pops up in any way except when people write Keyword arguments:, that's fine. (I was afraid that this would automatically create such sections where it didn't before). But I wouldn't change correct wording to wrong just to match this rare use case.

BTW they could instead describe kwargs as its own item within Args, with normal Markdown sub-lists in it

[pawamoy]

BTW they could instead describe kwargs as its own item within Args, with normal Markdown sub-lists in it

Yes that's what I initially replied in the original issue, #205.

I was afraid that this would automatically create such sections where it didn't before

Oh no, it's only rendered when a "Keyword arguments" section is found indeed.

But I wouldn't change correct wording to wrong just to match this rare use case.

Agreed. Then I'll totally revise what I said earlier, and change the new section title to "Keyword parameters". Maybe "Other parameters", from Numpydoc, would be even more appropriate.

[oprypin]

OK! Now no issue from my side.
I will not do a super careful review of all the content, so that's all.
Thanks

[pawamoy]

Thank you 🙂

[pawamoy]

Failures came from a precedent version of PDM which fixed the KeyError issue.