Question

版本1.3.4的sphinx-doc拿破仑Google风格文档字符串示例here显示函数/方法的可选参数应记录如下：

param2 (str, optional): The second parameter. Defaults to None.
  Second line of description should be indented.

但版本1.4a0 here的同一页面显示了以下相同的方法：

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

但我在the documentation中没有看到对这种新语法的任何解释。在哪里可以找到有关使用sphinx-doc的拿破仑扩展的Google风格文档字符串支持的新语法的更多信息？

Answer 1

以tl; dr方式：

查看function module_level_function that you linked开头的文档，可以看到：

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 ``Args`` section. The name
    of each parameter is required. The type and description of each parameter
    is optional, but should be included if not obvious.

    Parameter types -- if given -- should be specified according to
    `PEP 484`_, though `PEP 484`_ conformance isn't required or enforced.

    # ^^^^^ this! ^^^^

最后一行包含一个提示。显然， PEP 484 模块辅助的typing中引入的符号就是您所看到的。

符号的小介绍：

PEP 484基于PEP 3107中描述的功能注释;基本上每个函数参数在其名称后面都可以有一个可选的类型说明符。所以，对于像这样的函数：

def foo(a, b): 
    pass

您可以通过以下方式注释其类型：

def foo(a: int, b: str) -> None:
    pass

引入类型暗示带来需要形式化类型的方式;这是typing模块的用武之地。

typing模块包含一组很好的抽象类型（通常是类型理论mumbo-jumbo），您可以指定除标准内置函数之外的其他类型，例如int，{{1 }等。例如， Optional[str] 表示法指示参数可以采用str类型或str的“类型”，即它可选地为字符串。

因此简而言之，他们使用通过引入类型提示定义的符号来记录参数的类型。这意味着如果你有一个函数接受一个整数列表的参数：

None

它的文档应如下所示：

 def func(param1)

List[int]来自输入模块中的符号。

在哪里可以找到有关使用sphinx-doc的拿破仑扩展的Google风格文档字符串支持的新语法的更多信息？

2 个答案:

以tl; dr方式：

符号的小介绍：

更多例子：