`sphinx.ext.napoleon` – 支持NumPy和Google风格的文档字符串¶

模块作者：Rob Ruana

1.3 新版功能.

概观¶

你是否厌倦了编写看起来像这样的 docstrings 字符串:

: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是一个预处理器，它解析 NumPy 和 Google 样式的文档字符串，并在Sphinx尝试解析之前将它们转换为reStructuredText。当Sphinx处理文档时，这会在中间步骤中发生，因此它不会修改实际源代码文件中的任何文档字符串。

入门¶

之后设置Sphinx 来构建你的文档，在 Sphinx conf.py 文件中启用拿破仑:

# conf.py

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

使用 sphinx-apidoc 来构建您的API文档:

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

Docstrings¶

拿破仑解释每一个文档字符串 autodoc 可以找到，包括docstrings: modules ， classes ， attributes ， methods ， functions 和 variables 。在每个docstring中，特殊格式化的 Sections 被解析并转换为 reStructuredText 。

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

Docstring部分¶

支持以下所有节标题:

Args (参数的别名)

Arguments (参数的别名)

Attention

Attributes

Caution

Danger

Error

Example

Examples

Hint

Important

Keyword Args (关键字参数的别名)

Keyword Arguments

Methods

Note

Notes

Other Parameters

Parameters

Return (退货的别名)

Returns

Raises

References

See Also

Tip

Todo

Warning

Warnings (警告的别名)

Warns

Yield (收益率的别名)

Yields

Google与NumPy¶

拿破仑支持两种类型的文档字符串: 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风格更容易阅读。

Khan Academy 建议使用Google风格。

风格之间的选择很大程度上是审美的，但两种风格不应混为一谈。为您的项目选择一种样式并与之保持一致。

参见

完整的例子:

输入注释¶

PEP 484 引入了一种在Python代码中表达类型的标准方法。这是直接在docstrings中表达类型的替代方法。根据 PEP 484 表达类型的一个好处是类型检查器和IDE可以利用它们进行静态代码分析。

采用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

带有文档字符串类型的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

注解

Sphinx目前不支持 Python 2/3 compatible annotations ，并且不会在文档中显示。

配置¶

下面列出的是拿破仑使用的所有设置及其默认值。可以在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_google_docstring¶: 是的，可以解析 Google style docstrings。如果禁用对Google样式文档字符串的支持，则为false。 默认为True。

napoleon_numpy_docstring¶: 是真的解析 NumPy style docstrings。如果禁用对NumPy样式文档字符串的支持，则为false。 默认为True。

napoleon_include_init_with_doc¶

如果将 __init___ docstrings与类 docstring 分开列出，则为True。回到Sphinx的默认行为是错误的，它将 __init___ docstring 视为类文档的一部分。 默认为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¶

如果包含文档中的docstrings私有成员(如 _membername)，则为True。错误地回归到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¶

如果在文档中包含docstrings的特殊成员(例如 __membername__)，则为True。错误地回归到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¶

对于 Example 和 Example 部分，使用 .. admonition:: 指令。错误地使用 .. 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¶: 对于 Notes 部分，使用 .. admonition:: 指令。错误地使用 .. rubric:: 指令。 默认为False。

注解

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

参见

napoleon_use_admonition_for_examples

napoleon_use_admonition_for_references¶: 对于 References 部分，使用 .. admonition:: 指令。错误地使用 .. rubric:: 指令。 默认为False。

参见

napoleon_use_admonition_for_examples

napoleon_use_ivar¶

如果为实例变量，则使用 :ivar: 角色。错误地使用 .. 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: 角色为假。 默认为 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: 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: 角色是错误的。 默认为 True。

其行为类似于 napoleon_use_param 。请注意，与docutils不同，:keyword: 和 :param: 将不会以同样的方式处理 - 将有一个单独的 “关键字参数” 部分，以与“参数 “相同的方式呈现” 部分(如果可能，创建类型链接)

参见

napoleon_use_param

napoleon_use_rtype¶

如果为返回类型，则使用 :rtype: 角色。如果输出与描述内联的返回类型，则返回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

目录

上一个主题

下一个主题

本页

`sphinx.ext.napoleon` – 支持NumPy和Google风格的文档字符串¶

概观¶

入门¶

Docstrings¶

Docstring部分¶

Google与NumPy¶

输入注释¶

配置¶

sphinx.ext.napoleon – 支持NumPy和Google风格的文档字符串¶

概观¶

入门¶

Docstrings¶

Docstring部分¶

Google与NumPy¶

输入注释¶

配置¶

`sphinx.ext.napoleon` – 支持NumPy和Google风格的文档字符串¶