sphinx.ext.napoleon – 支持 NumPy 和 Google 样式文档字符串¶
模块作者：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 非常棒，但它创建的视觉效果密集、难以阅读的文档字符串。将上面的混乱与根据Google Python 风格指南重写的相同内容进行比较
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 是一种扩展，它使 Sphinx 能够解析NumPy 和Google 样式文档字符串 - 由可汗学院推荐的样式。
Napoleon 是一种预处理器，它解析NumPy 和Google 样式文档字符串，并在 Sphinx 尝试解析它们之前将其转换为 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 可以找到的每个文档字符串，包括以下内容的文档字符串：模块、类、属性、方法、函数 和 变量。在每个文档字符串中，将解析特殊格式的章节并转换为 reStructuredText。
所有标准的 reStructuredText 格式仍然按预期工作。
文档字符串章节¶
支持以下所有章节标题
Args（Parameters 的别名）Arguments（Parameters 的别名）注意属性警告危险错误示例示例提示重要Keyword Args（关键字参数的别名）Keyword Arguments方法注意注释Other Parameters参数Return（Returns 的别名）返回Raise（Raises 的别名）引发参考See Also提示待办事项警告Warnings（Warning 的别名）Warn（Warns 的别名）警告Yield（Yields 的别名）生成
Google 与 NumPy¶
Napoleon 支持两种样式的文档字符串：Google 和NumPy。这两种样式之间的主要区别在于，Google 使用缩进分隔章节，而 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 样式往往需要更多垂直空间，而 Google 样式往往使用更多水平空间。对于短小简单的文档字符串，Google 样式往往更容易阅读，而对于长而深入的文档字符串，NumPy 样式往往更容易阅读。
样式之间的选择很大程度上是美观的，但两种样式不应混合使用。为您的项目选择一种样式并保持一致。
类型注解¶
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 文件中更改。确保在 conf.py 中启用了“sphinx.ext.napoleon”
# 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_include_init_with_doc¶
如果为 True，则将
__init___文档字符串与类文档字符串分开列出。如果为 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¶
如果为 True，则在文档中包含带有文档字符串的私有成员（如
_membername）。如果为 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¶
如果为 True，则在文档中包含带有文档字符串的特殊成员（如
__membername__）。如果为 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¶
是否使用
.. admonition::指令用于 Example 和 Examples 部分。如果为 False，则改为使用.. rubric::指令。根据使用的 HTML 主题，其中一个可能比另一个看起来更好。默认为 False。此 NumPy 风格 代码段将按如下方式转换
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¶
是否使用
.. admonition::指令用于 Notes 部分。如果为 False，则改为使用.. rubric::指令。默认为 False。注意
单个 Note 部分将始终转换为
.. note::指令。
- napoleon_use_admonition_for_references¶
是否使用
.. admonition::指令用于 References 部分。如果为 False，则改为使用.. rubric::指令。默认为 False。
- napoleon_use_ivar¶
是否使用
:ivar:角色表示实例变量。如果为 False，则改为使用.. attribute::指令。默认为 False。此 NumPy 风格 代码段将按如下方式转换
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:角色。如果为 False，则为所有参数使用单个:parameters:角色。默认为 True。此 NumPy 风格 代码段将按如下方式转换
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:角色。如果为 False，则为所有关键字使用单个:keyword arguments:角色。默认为 True。其行为类似于
napoleon_use_param。请注意，与 docutils 不同，:keyword:和:param:不会以相同的方式处理 - 将会有一个单独的“关键字参数”部分，其呈现方式与“参数”部分相同（如果可能，则创建类型链接）另请参阅
- napoleon_use_rtype¶
是否使用
:rtype:角色表示返回类型。如果为 False，则将返回类型与描述内联输出。默认为 True。此 NumPy 风格 代码段将按如下方式转换
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¶
是否将文档字符串中的类型定义转换为引用。默认为 False。
版本 3.2.1 中新增。
版本 3.5 中更改： 也预处理 Google 风格的文档字符串。
- 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_custom_sections¶
添加要包含的自定义部分列表，扩展已解析部分的列表。默认为 None。
条目可以是字符串或元组，具体取决于意图
要创建自定义“通用”部分，只需传递一个字符串。
要为现有部分创建别名，请按顺序传递包含别名和原名的元组。
要创建类似于参数或返回值部分显示的自定义部分，请传递包含自定义部分名称和字符串值“params_style”或“returns_style”的元组。
如果条目只是一个字符串，则将其解释为通用部分的标题。如果条目是元组/列表/索引容器，则第一个条目是部分的名称，第二个条目是要模拟的部分键。如果第二个条目的值为“params_style”或“returns_style”，则自定义部分将显示为参数部分或返回值部分。
版本 1.8 中新增。
版本 3.5 中更改： 支持
params_style和returns_style