Keyword Arguments section purpose is unclear

[rgommers]

I started looking into this after finding out that PyTorch uses the Keyword Arguments section only for keyword-only parameters. Reading the Napoleon docs and source code, it's completely unclear if that's what this section was meant for.

Here is the result of some digging: the Keyword Arguments name is coming from

napoleon/sphinxcontrib/napoleon/docstring.py

Line 673 in 83bf196

return self._format_fields(_('Keyword Arguments'), fields)

. Nowhere does Napoleon make clear whether that's meant as keyword-only yes or no. The other odd thing is that Napoleon implements two docstring styles (Google or NumPy), and neither has Keyword Arguments as a separate section. Google just has Args and NumPy only Parameters.

Napoleon introduced it in this commit, which points to the Khan Academy style guide. But that style guide now follows Google style: https://github.com/Khan/style-guides/blob/master/style/python.md#docstrings.

It would probably be useful to recommend in the Napoleon docs not to use this section, because neither Google nor NumPy doc styles have it, and it's confusing the way PyTorch uses it.