如何正确地记录**kwargs参数？

Question

我正在使用Sphinx和autodoc扩展来为我的Python模块生成API文档。虽然我知道怎么清楚地记录特定的参数，但我找不到如何记录**kwargs参数的例子。

有没有人能提供一个清晰的例子来说明该怎么记录这些参数呢？

Answer 1

Google风格的文档字符串在Sphinx中的解析

免责声明：未经过测试。

在这个来自Sphinx文档字符串示例的片段中，*args和**kwargs被保留原样：

def module_level_function(param1, *args, param2=None, **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 
        ...

注意，Optional并不是**key参数的必需项。

另外，你可以尝试在其他参数下明确列出*args，在关键字参数下列出**kwargs（见文档字符串部分）：

    """
    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 
        ...

Answer 2

在看到这个问题后，我决定使用以下方法，这个方法是有效的Sphinx格式，并且效果还不错：

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"""..."""是必须的，它可以让这个文档字符串变成“原始”的，这样就能保持\*不变（让Sphinx把它当作字面上的*处理，而不是当作“强调”的开始）。

我选择的格式（带有括号的类型和用破折号分隔的描述的项目符号列表）只是为了和Sphinx自动提供的格式保持一致。

既然你已经花了力气让“关键字参数”部分看起来像默认的“参数”部分，那么从一开始就自己创建一个参数部分似乎会更简单（就像其他一些回答提到的那样）。不过，作为一个概念验证，这是一种在你已经使用Sphinx的情况下，让补充的**kwargs看起来不错的方法。

Answer 3

我觉得subprocess模块的文档是个很好的例子。它详细列出了一个顶级/父类的所有参数。然后在其他地方只需要引用这个参数列表就可以了，特别是对于那些用到**kwargs的地方。