`sphinx.ext.napoleon` —— 支持 NumPy 和谷歌风格的文档字符串¶

模块作者： Rob Ruana

1.3 新版功能.

概述¶

您是否厌倦了编写这样的文档字符串

:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File
   instance is destructed
:type temporary: bool
:returns: A buffered writable file descriptor
:rtype: BufferedFileStorage

reStructuredText 很好，但它创建了视觉密集，难以阅读 docstrings。将上面的混乱与根据 Google Python Style Guide 重写的相同内容进行比较:

Args:
    path (str): The path of the file to wrap
    field_storage (FileStorage): The :class:`FileStorage` instance to wrap
    temporary (bool): Whether or not to delete the file when the File
       instance is destructed

Returns:
    BufferedFileStorage: A buffered writable file descriptor

更清晰，不是吗？

Napoleon 是一个 extension，它使 Sphinx 能够同时解析 NumPy 和 Google 风格的文档字符串——这是 Khan Academy 推荐的风格。

Napoleon 是一个预处理器，在 Sphinx 试图解析它们之前，它会解析 NumPy 和 Google 风格的文档字符串，并将它们转换为 reStructuredText。这发生在 Sphinx 处理文档的中间步骤中，所以它不会修改实际源代码文件中的任何文档字符串。

入门¶

在设置了 Sphinx 来构建文档之后，在 Sphinx conf.py 文件中启用 napoleon

# conf.py

# Add napoleon to the extensions list
extensions = ['sphinx.ext.napoleon']

使用 sphinx-apidoc 构建你的 API 文档

$ sphinx-apidoc -f -o docs/source projectdir

文档字符串¶

Napoleon 解释了 autodoc 可以找到的所有文档字符串，包括：modules、classes、attributes、methods、functions 和 variables 上的文档字符串。在每个文档字符串中，特殊格式的 Sections 被解析并转换为 reStructuredText。

所有标准的 reStructuredText 格式仍然按预期工作。

文档字符串部分¶

支持以下所有节头文件：

Args （Parameters 的别名）

Arguments （Parameters 的别名）

Attention

Attributes

Caution

Danger

Error

Example

Examples

Hint

Important

Keyword Args (alias of Keyword Arguments)

Keyword Arguments

Methods

Note

Notes

Other Parameters

Parameters

Return (alias of Returns)

Returns

Raise (alias of Raises)

Raises

References

See Also

Tip

Todo

Warning

Warnings (alias of Warning)

Warn (alias of Warns)

Warns

Yield (alias of Yields)

Yields

Google vs NumPy¶

Napoleon 支持两种类型的文档字符串：Google 和 NumPy。这两种风格的主要区别是谷歌使用缩进来分隔部分，而 NumPy 使用下划线。

Google 风格：

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

NumPy 风格：

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    """
    return True

NumPy 风格往往需要更多的垂直空间，而谷歌风格往往使用更多的水平空间。谷歌风格更容易阅读短而简单的文档字符串，而 NumPy 风格更容易阅读长而深入的文档字符串。

Khan Academy 推荐使用谷歌风格。

风格之间的选择主要是审美，但两种风格不应该混合在一起。为你的项目选择一种风格，并保持一致。

参见

完整的例子：

类型注解¶

PEP 484 引入了一种用 Python 代码表达类型的标准方式。这是一个替代直接在文档字符串中表达类型的方法。根据 PEP 484 表示类型的一个好处是，类型检查器和 IDE 可以利用它们进行静态代码分析。然后，PEP 484 被 PEP 526 扩展，后者引入了一种类似的方式来注释变量（和属性）。

使用 Python 3 类型注释的 Google 样式

def func(arg1: int, arg2: str) -> bool:
    """Summary line.

    Extended description of function.

    Args:
        arg1: Description of arg1
        arg2: Description of arg2

    Returns:
        Description of return value

    """
    return True

class Class:
    """Summary line.

    Extended description of class

    Attributes:
        attr1: Description of attr1
        attr2: Description of attr2
    """

    attr1: int
    attr2: str

文档字符串类型的 Google 样式

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

class Class:
    """Summary line.

    Extended description of class

    Attributes:
        attr1 (int): Description of attr1
        attr2 (str): Description of attr2
    """

备注

Python 2/3 兼容的注释目前不被 Sphinx 支持，也不会出现在文档中。

配置¶

下面列出的是 napoleon 使用的所有设置和它们的默认值。这些设置可以在 Sphinx conf.py 文件中更改。确保 “sphinx.ext.napoleon” 在 conf.py 中启用

# conf.py

# Add any Sphinx extension module names here, as strings
extensions = ['sphinx.ext.napoleon']

# Napoleon settings
napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = False
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = False
napoleon_use_admonition_for_notes = False
napoleon_use_admonition_for_references = False
napoleon_use_ivar = False
napoleon_use_param = True
napoleon_use_rtype = True
napoleon_preprocess_types = False
napoleon_type_aliases = None
napoleon_attr_annotations = True

napoleon_google_docstring¶: True 用于解析谷歌风格文档字符串。False 禁用对谷歌风格文档字符串的支持。默认值为 True。

napoleon_numpy_docstring¶: True 解析 NumPy 风格文档字符串。False 禁用对 NumPy 样式文档字符串的支持。默认值为 True。

napoleon_include_init_with_doc¶

将 __init___ 文档字符串与类文档字符串分开列出为 True。False 返回 Sphinx 的默认行为，它将 __init___ 文档字符串视为类文档的一部分。默认为 False。

如果为 True:

def __init__(self):
    """
    This will be included in the docs because it has a docstring
    """

def __init__(self):
    # This will NOT be included in the docs

napoleon_include_private_with_doc¶

在文档中使用文档字符串包含私有成员（如 _membername）为 True。False 返回 Sphinx 的默认行为。默认为 False。

如果为 True:

def _included(self):
    """
    This will be included in the docs because it has a docstring
    """
    pass

def _skipped(self):
    # This will NOT be included in the docs
    pass

napoleon_include_special_with_doc¶

在文档中包含带有文档字符串的特殊成员（如 __membername__）为 True。False 返回到 Sphinx 的默认行为。默认值为 True。

如果为 True:

def __str__(self):
    """
    This will be included in the docs because it has a docstring
    """
    return unicode(self).encode('utf-8')

def __unicode__(self):
    # This will NOT be included in the docs
    return unicode(self.__class__.__name__)

napoleon_use_admonition_for_examples¶

True 在 Example 和 Example 部分中使用 .. admonition:: 指令。False 来代替 .. rubric:: 指令。一种可能比另一种看起来更好，这取决于所使用的 HTML 主题。默认值为 False。

这个 NumPy style 片段将被转换如下:

Example
-------
This is just a quick example

如果为 True:

.. admonition:: Example

   This is just a quick example

如果为 False:

.. rubric:: Example

This is just a quick example

napoleon_use_admonition_for_notes¶: True 在 Notes 部分中使用 .. admonition:: 指令。False 来代替 .. rubric:: 指令。默认值为 False。

备注

Note 的单数部分将始终被转换为 .. note:: 指令。

参见

napoleon_use_admonition_for_examples

napoleon_use_admonition_for_references¶: 使用 .. admonition:: 指示用于 References 节。使用 .. rubric:: 指令时为 False。默认为 False。

参见

napoleon_use_admonition_for_examples

napoleon_use_ivar¶

为实例变量使用 :ivar: 角色时为 True。False 使用 .. attribute:: 指令代替。默认为 False。

这个 NumPy style 片段将被转换如下:

Attributes
----------
attr1 : int
    Description of `attr1`

如果为 True:

:ivar attr1: Description of `attr1`
:vartype attr1: int

如果为 False:

.. attribute:: attr1

   Description of `attr1`

   :type: int

napoleon_use_param¶

为每个函数参数使用 :param: 角色时为 True。为所有参数使用单一的 :parameters: 角色为 False。默认值为 True。

这个 NumPy style 片段将被转换如下:

Parameters
----------
arg1 : str
    Description of `arg1`
arg2 : int, optional
    Description of `arg2`, defaults to 0

如果为 True:

:param arg1: Description of `arg1`
:type arg1: str
:param arg2: Description of `arg2`, defaults to 0
:type arg2: :class:`int`, *optional*

如果为 False:

:parameters: * **arg1** (*str*) --
               Description of `arg1`
             * **arg2** (*int, optional*) --
               Description of `arg2`, defaults to 0

napoleon_use_keyword¶

为每个函数关键字参数使用 :keyword: 角色为 True。为所有关键字使用单一的 :keyword arguments: 角色为False。默认值为 True。

它的行为类似于 napoleon_use_param。注意，不像 docutils， :keyword: 和 :param: 将不会被相同的方式对待——将会有一个单独的 “Keyword Arguments” 部分，以相同的方式呈现 “Parameters” 部分（如果可能创建类型链接）

参见

napoleon_use_param

napoleon_use_rtype¶

使用 :rtype: 角色作为返回类型时为 True。False 表示将返回类型与描述内联输出。默认值为 True。

这个 NumPy style 片段将被转换如下:

Returns
-------
bool
    True if successful, False otherwise

如果为 True:

:returns: True if successful, False otherwise
:rtype: bool

如果为 False:

:returns: *bool* -- True if successful, False otherwise

napoleon_preprocess_types¶: True 将文档字符串中的类型定义转换为引用。默认为 False。

3.2.1 新版功能.

在 3.5 版更改: 也对谷歌风格的文档字符串进行预处理。

napoleon_type_aliases¶

将类型名称转换为其他名称或引用的映射。仅当 napoleon_use_param = True 时有效。默认为 None。

使用

napoleon_type_aliases = {
    "CustomType": "mypackage.CustomType",
    "dict-like": ":term:`dict-like <mapping>`",
}

这是 NumPy 风格片段:

Parameters
----------
arg1 : CustomType
    Description of `arg1`
arg2 : dict-like
    Description of `arg2`

成为

:param arg1: Description of `arg1`
:type arg1: mypackage.CustomType
:param arg2: Description of `arg2`
:type arg2: :term:`dict-like <mapping>`

3.2 新版功能.

napoleon_attr_annotations¶: True 表示允许在类中使用 PEP 526 属性注解。如果一个属性在没有类型的文档字符串中被记录，并且在类主体中有注解，则使用该类型。

3.4 新版功能.

napoleon_custom_sections¶

添加要包含的自定义部分列表，展开已解析部分列表。默认为 None。

条目可以是字符串，也可以是元组，这取决于意图：

要创建一个自定义的 “generic” 节，只需传递一个字符串。
要为现有的 section 创建别名，请按顺序传递一个包含别名和原始 section 的元组。
要创建一个显示参数或返回 section 的自定义 section，传递一个包含自定义 section 名和字符串值的元组，”params_style” 或 “returns_style”。

如果一个条目只是一个字符串，它会被解释为 generic 节的头文件。如果条目是一个元组/列表/索引容器，第一个条目是 section 的名称，第二个是要模拟的 section 键。如果第二个条目值是 “params_style” 或 “returns_style”，自定义部分将像 parameters 部分或 returns 部分一样显示。

1.8 新版功能.

在 3.5 版更改: 支持 params_style 和 returns_style

目录

上一个主题

下一个主题

本页

`sphinx.ext.napoleon` —— 支持 NumPy 和谷歌风格的文档字符串¶

概述¶

入门¶

文档字符串¶

文档字符串部分¶

Google vs NumPy¶

类型注解¶

配置¶

sphinx.ext.napoleon —— 支持 NumPy 和谷歌风格的文档字符串¶

概述¶

入门¶

文档字符串¶

文档字符串部分¶

Google vs NumPy¶

类型注解¶

配置¶

`sphinx.ext.napoleon` —— 支持 NumPy 和谷歌风格的文档字符串¶