记录**kwargs参数的正确方法是什么？

Question

我正在使用sphinx和autodoc插件为我的Python模块生成API文档。虽然我可以看到如何很好地记录特定参数，但找不到如何记录**kwargs参数的示例。

有没有人有一个很好的例子来清楚地记录这些？

Answer 1

我认为^{}-module's docs是一个很好的例子。给出top/parent class的所有参数的详尽列表。然后，只需参考该列表中所有其他出现的**kwargs。

Answer 2

在找到这个问题后，我解决了以下问题，这是一个有效的狮身人面像，工作得相当好：

def some_function(first, second="two", **kwargs):
    r"""Fetches and returns this thing

    :param first:
        The first parameter
    :type first: ``int``
    :param second:
        The second parameter
    :type second: ``str``
    :param \**kwargs:
        See below

    :Keyword Arguments:
        * *extra* (``list``) --
          Extra stuff
        * *supplement* (``dict``) --
          Additional content

    """

需要r"""..."""才能使其成为“原始”docstring，从而保持\*的完整性（Sphinx将其作为文本*，而不是“emphasis”的开头）。

所选择的格式（带括号类型的项目符号列表和m-dash分隔的描述）只是为了与Sphinx提供的自动格式匹配。

一旦你努力使“关键字参数”部分看起来像默认的“参数”部分，似乎从一开始滚动你自己的参数部分会更容易（根据其他一些答案），但作为概念的证明，如果您已经在使用Sphinx，这是一种很好地寻找补充**kwargs的方法。

Answer 3

Sphinx解析的谷歌风格文档字符串

免责声明：未经测试。

从sphinx docstring example的这个剪切中，*args和**kwargs未展开：

def module_level_function(param1, param2=None, *args, **kwargs):
    """
    ...

    Args:
        param1 (int): The first parameter.
        param2 (Optional[str]): The second parameter. Defaults to None.
            Second line of description should be indented.
        *args: Variable length argument list.
        **kwargs: Arbitrary keyword arguments.

我建议用以下方法解决压实度问题：

    """
    Args:
        param1 (int): The first parameter.
        param2 (Optional[str]): The second parameter. Defaults to None.
            Second line of description should be indented.
        *param3 (int): description
        *param4 (str): 
        ...
        **key1 (int): description 
        **key2 (int): description 
        ...

注意，**key参数不需要Optional。

否则，可以尝试在Other Parameters下显式列出*参数，在Keyword Args下显式列出**kwargs（请参阅解析的sections）：

    """
    Args:
        param1 (int): The first parameter.
        param2 (Optional[str]): The second parameter. Defaults to None.
            Second line of description should be indented.

    Other Parameters:
        param3 (int): description
        param4 (str): 
        ...

    Keyword Args:
        key1 (int): description 
        key2 (int): description 
        ...