如何根据 Numpy 风格的文档字符串记录 kwargs？
How to document kwargs according to Numpy style docstring?
所以，我找到了与其他样式相关的帖子，并且我知道 this NumPy 页面上关于文档的内容，但我很困惑。我不明白如何将每个 kwargs 添加到方法的参数部分。这来自给定的网页：
def foo(var1, var2, *args, long_var_name='hi', **kwargs):
r"""Summarize the function in one line.
Several sentences providing an extended description. Refer to
variables using back-ticks, e.g. `var`.
Parameters
----------
var1 : array_like
Array_like means all those objects -- lists, nested lists, etc. --
that can be converted to an array. We can also refer to
variables like `var1`.
var2 : int
The type above can either refer to an actual Python type
(e.g. ``int``), or describe the type of the variable in more
detail, e.g. ``(N,) ndarray`` or ``array_like``.
*args : iterable
Other arguments.
long_var_name : {'hi', 'ho'}, optional
Choices in brackets, default first when optional.
**kwargs : dict
Keyword arguments.
不清楚如何在此处添加每个 kwargs。我还看到了这个 sphinx 页面 "Example NumPy Style Python Docstring"，这里是关于 kwargs 的部分：
def module_level_function(param1, param2=None, *args, **kwargs):
"""This is an example of a module level function.
Function parameters should be documented in the ``Parameters`` section.
The name of each parameter is required. The type and description of each
parameter is optional, but should be included if not obvious.
If \*args or \*\*kwargs are accepted,
they should be listed as ``*args`` and ``**kwargs``.
The format for a parameter is::
name : type
description
The description may span multiple lines. Following lines
should be indented to match the first line of the description.
The ": type" is optional.
Multiple paragraphs are supported in parameter
descriptions.
Parameters
----------
param1 : int
The first parameter.
param2 : :obj:`str`, optional
The second parameter.
*args
Variable length argument list.
**kwargs
Arbitrary keyword arguments.
不行，我还是一头雾水。是这样的吗？
"""
Dummy docstring.
Parameters
----------
**kwargs: dict
first_kwarg: int
This is an integer
second_kwarg: str
This is a string
"""
通常，需要在 Parameters 部分中描述的 kwargs 通常会像其他命名参数一样处理，并且 **kwargs 未展开。然而，numpy 风格指南也有一个 Other Parameters 部分，可用于提供 kwargs 的描述，而不会使 Parameters 部分混乱。 style guide 将其描述为：
An optional section used to describe infrequently used parameters. It should only be used if a function has a large number of keyword parameters, to prevent cluttering the Parameters section.
numpydoc repo gives this example:
"""
Other Parameters
----------------
only_seldom_used_keyword : int, optional
Infrequently used parameters can be described under this optional
section to prevent cluttering the Parameters section.
**kwargs : dict
Other infrequently used keyword arguments. Note that all keyword
arguments appearing after the first parameter specified under the
Other Parameters section, should also be described under this
section.
"""
因此，可以添加额外的 kwargs
"""
Other Parameters
----------------
first_kwarg: int
This is an integer
second_kwarg: str
This is a string
**kwargs : dict
Other infrequently used keyword arguments.
"""
总结
**kwargs 通常不会在函数中列出，而是提及 **kwargs 的最终目的地。例如：
**kwargs
Instructions on how to decorate your plots.
The keyword arguments are passed to `matplotlib.axes.Axes.plot()`
- 如果有多个可能的目标，则全部列出（见下文）
- 如果您碰巧使用一些自动化工具来插入和 link 您的文档，那么您可能会在
**kwargs 中列出可能的关键字参数以方便最终用户。例如，这种方法在 matplotlib 中使用。 （见下文）
如何以及何时文档 **kwargs (Numpydoc)
1) 什么时候使用**kwargs?
这里首先要注意的是 **kwargs 应该用于 将参数传递给基础函数和方法 。如果 **kwargs 中的参数将在函数中使用（而不是向下传递），则应将其写为普通关键字参数。
2) **kwargs描述放在哪里？
**kwargs描述的位置在Parameters部分。有时将它们列在 Other Parameters 部分是合适的，但请记住：Other Parameters 仅应在函数具有大量关键字参数时使用，以防止 Parameters 部分混乱。
matplotlib.axes.Axes.grid 在 Parameters 部分有 **kwargs。matplotlib.axes.Axes.plot 在 Other Parameters 部分有 **kwargs（推理可能涉及大量关键字参数）。
3) **kwargs 描述的语法
**kwargs 的描述 的语法是，遵循Numpydoc styleguide
Parameters
----------
... (other lines)
**kwargs : sometype
Some description on what the kwargs are
used for.
或
Parameters
----------
... (other lines)
**kwargs
Some description on what the kwargs are
used for.
描述类型的更合适，如[source].
For the parameter types, be as precise as possible
例如，当 **kwargs 可以根据其他参数值 传递给许多函数之一时，如 seaborn.kdeplot .然后，类型的行会变得太长而无法描述所有类型，使用项目符号列表会更清晰，它还描述了 **kwargs 何时转发到何处的条件。例如：
Parameters
----------
fill: bool or None
If True, fill in the area under univariate density curves or between
bivariate contours. If None, the default depends on multiple.
**kwargs
Other keyword arguments are passed to one of the following matplotlib
functions:
* matplotlib.axes.Axes.plot() (univariate, fill=False),
* matplotlib.axes.Axes.fill_between() (univariate, fill=True),
* matplotlib.axes.Axes.contour() (bivariate, fill=False),
* matplotlib.axes.contourf() (bivariate, fill=True).
您还可以在 **kwargs 中添加 有效关键字参数的列表，就像在 matplotlib.axes.Axes.grid 中一样。这是内插的 python doc/text 版本：
Parameters
----------
... (other lines)
**kwargs : `.Line2D` properties
Define the line properties of the grid, e.g.::
grid(color='r', linestyle='-', linewidth=2)
Valid keyword arguments are:
Properties:
agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha: float or None
animated: bool
antialiased or aa: bool
clip_box: `.Bbox`
clip_on: bool
clip_path: Patch or (Path, Transform) or None
color or c: color
contains: unknown
dash_capstyle: {'butt', 'round', 'projecting'}
dash_joinstyle: {'miter', '
... (more lines)
这对用户来说很方便，但对开发者来说是一个挑战。在 matplotlib 中，这种奢侈是通过使用一些特殊的文档装饰器和 linking1 的自动化实现的。手动编写允许的 kwargs 肯定会成为代码维护的噩梦。
4) 与 **kwargs/扩展帮助相关的注释
关于 **kwargs 的一些 附加信息 可以包含在 Notes 部分中。
例如 matplotlib.axes.Axes.plot 在 Notes 部分讨论了标记样式、线条样式和颜色。 [2]
[1] 他们使用 @docstring.dedent_interpd 装饰器将 kwargs 的含义提取到最终文档中。例如，这取代了 %(Line2D:kwdoc)s。
[2] 请参阅：help(ax.plot) 其中 ax 是 matplotlib.axes.Axes.
的实例
所以，我找到了与其他样式相关的帖子，并且我知道 this NumPy 页面上关于文档的内容，但我很困惑。我不明白如何将每个 kwargs 添加到方法的参数部分。这来自给定的网页：
def foo(var1, var2, *args, long_var_name='hi', **kwargs):
r"""Summarize the function in one line.
Several sentences providing an extended description. Refer to
variables using back-ticks, e.g. `var`.
Parameters
----------
var1 : array_like
Array_like means all those objects -- lists, nested lists, etc. --
that can be converted to an array. We can also refer to
variables like `var1`.
var2 : int
The type above can either refer to an actual Python type
(e.g. ``int``), or describe the type of the variable in more
detail, e.g. ``(N,) ndarray`` or ``array_like``.
*args : iterable
Other arguments.
long_var_name : {'hi', 'ho'}, optional
Choices in brackets, default first when optional.
**kwargs : dict
Keyword arguments.
不清楚如何在此处添加每个 kwargs。我还看到了这个 sphinx 页面 "Example NumPy Style Python Docstring"，这里是关于 kwargs 的部分：
def module_level_function(param1, param2=None, *args, **kwargs):
"""This is an example of a module level function.
Function parameters should be documented in the ``Parameters`` section.
The name of each parameter is required. The type and description of each
parameter is optional, but should be included if not obvious.
If \*args or \*\*kwargs are accepted,
they should be listed as ``*args`` and ``**kwargs``.
The format for a parameter is::
name : type
description
The description may span multiple lines. Following lines
should be indented to match the first line of the description.
The ": type" is optional.
Multiple paragraphs are supported in parameter
descriptions.
Parameters
----------
param1 : int
The first parameter.
param2 : :obj:`str`, optional
The second parameter.
*args
Variable length argument list.
**kwargs
Arbitrary keyword arguments.
不行，我还是一头雾水。是这样的吗？
"""
Dummy docstring.
Parameters
----------
**kwargs: dict
first_kwarg: int
This is an integer
second_kwarg: str
This is a string
"""
通常，需要在 Parameters 部分中描述的 kwargs 通常会像其他命名参数一样处理，并且 **kwargs 未展开。然而，numpy 风格指南也有一个 Other Parameters 部分，可用于提供 kwargs 的描述，而不会使 Parameters 部分混乱。 style guide 将其描述为：
An optional section used to describe infrequently used parameters. It should only be used if a function has a large number of keyword parameters, to prevent cluttering the Parameters section.
numpydoc repo gives this example:
"""
Other Parameters
----------------
only_seldom_used_keyword : int, optional
Infrequently used parameters can be described under this optional
section to prevent cluttering the Parameters section.
**kwargs : dict
Other infrequently used keyword arguments. Note that all keyword
arguments appearing after the first parameter specified under the
Other Parameters section, should also be described under this
section.
"""
因此，可以添加额外的 kwargs
"""
Other Parameters
----------------
first_kwarg: int
This is an integer
second_kwarg: str
This is a string
**kwargs : dict
Other infrequently used keyword arguments.
"""
总结
**kwargs 通常不会在函数中列出，而是提及 **kwargs 的最终目的地。例如：
**kwargs
Instructions on how to decorate your plots.
The keyword arguments are passed to `matplotlib.axes.Axes.plot()`
- 如果有多个可能的目标，则全部列出（见下文）
- 如果您碰巧使用一些自动化工具来插入和 link 您的文档，那么您可能会在
**kwargs中列出可能的关键字参数以方便最终用户。例如，这种方法在 matplotlib 中使用。 （见下文）
如何以及何时文档 **kwargs (Numpydoc)
1) 什么时候使用**kwargs?
这里首先要注意的是 **kwargs 应该用于 将参数传递给基础函数和方法 。如果 **kwargs 中的参数将在函数中使用（而不是向下传递），则应将其写为普通关键字参数。
2) **kwargs描述放在哪里？
**kwargs描述的位置在Parameters部分。有时将它们列在 Other Parameters 部分是合适的，但请记住：Other Parameters 仅应在函数具有大量关键字参数时使用，以防止 Parameters 部分混乱。
matplotlib.axes.Axes.grid在Parameters部分有**kwargs。matplotlib.axes.Axes.plot在Other Parameters部分有**kwargs（推理可能涉及大量关键字参数）。
3) **kwargs 描述的语法
**kwargs 的描述 的语法是，遵循Numpydoc styleguide
Parameters
----------
... (other lines)
**kwargs : sometype
Some description on what the kwargs are
used for.
或
Parameters
----------
... (other lines)
**kwargs
Some description on what the kwargs are
used for.
描述类型的更合适，如[source].
For the parameter types, be as precise as possible
例如，当 **kwargs 可以根据其他参数值 传递给许多函数之一时，如 seaborn.kdeplot .然后，类型的行会变得太长而无法描述所有类型，使用项目符号列表会更清晰，它还描述了 **kwargs 何时转发到何处的条件。例如：
Parameters
----------
fill: bool or None
If True, fill in the area under univariate density curves or between
bivariate contours. If None, the default depends on multiple.
**kwargs
Other keyword arguments are passed to one of the following matplotlib
functions:
* matplotlib.axes.Axes.plot() (univariate, fill=False),
* matplotlib.axes.Axes.fill_between() (univariate, fill=True),
* matplotlib.axes.Axes.contour() (bivariate, fill=False),
* matplotlib.axes.contourf() (bivariate, fill=True).
您还可以在 **kwargs 中添加 有效关键字参数的列表，就像在 matplotlib.axes.Axes.grid 中一样。这是内插的 python doc/text 版本：
Parameters
----------
... (other lines)
**kwargs : `.Line2D` properties
Define the line properties of the grid, e.g.::
grid(color='r', linestyle='-', linewidth=2)
Valid keyword arguments are:
Properties:
agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha: float or None
animated: bool
antialiased or aa: bool
clip_box: `.Bbox`
clip_on: bool
clip_path: Patch or (Path, Transform) or None
color or c: color
contains: unknown
dash_capstyle: {'butt', 'round', 'projecting'}
dash_joinstyle: {'miter', '
... (more lines)
这对用户来说很方便，但对开发者来说是一个挑战。在 matplotlib 中，这种奢侈是通过使用一些特殊的文档装饰器和 linking1 的自动化实现的。手动编写允许的 kwargs 肯定会成为代码维护的噩梦。
4) 与 **kwargs/扩展帮助相关的注释
关于 **kwargs 的一些 附加信息 可以包含在 Notes 部分中。
例如 matplotlib.axes.Axes.plot 在 Notes 部分讨论了标记样式、线条样式和颜色。 [2]
[1] 他们使用 @docstring.dedent_interpd 装饰器将 kwargs 的含义提取到最终文档中。例如，这取代了 %(Line2D:kwdoc)s。
[2] 请参阅：help(ax.plot) 其中 ax 是 matplotlib.axes.Axes.