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.
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.
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 https://github.com/sphinx-contrib/napoleon/blob/83bf1963096490dd666f93ef5a9ed1cb229fc3ec/sphinxcontrib/napoleon/docstring.py#L673. 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 hasKeyword Arguments
as a separate section. Google just hasArgs
and NumPy onlyParameters
.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.