`sphinx.ext.autodoc` -- 纳入来自docstrings的文档¶

此扩展导入需要生成文档的模块，并以半自动的方式从文档字符串中拉入文档。

警告

autodoc 导入需要生成文档的模块。如果任何模块在导入时具有副作用，这些副作用将在运行 sphinx-build 时由 autodoc 执行。

如果要给脚本（而不是库模块）生成文档，请确保主函数由 if __name__ == '__main__' 保护。

为了autodoc可以正常工作，docstrings当然必须用正确的reStructuredText编写。然后，您可以在docstrings中使用所有常用的Sphinx标记，它最终将正确地出现在文档中。结合手写文档，这种技术减轻了维护两个文档位置的痛苦，同时避免了自动生成的纯API文档的外观。

如果您更喜欢 NumPy 或 Google 风格的docstrings而不是reStructuredText风格的，您还可以启用 napoleon 扩展。napoleon 是一个预处理器，在 autodoc 处理它们之前将docstrings转换为正确的reStructuredText。

开始¶

设置¶

在 conf.py 的 extensions 列表中添加 'sphinx.ext.autodoc' 来激活该插件：

extensions = [
    ...
    'sphinx.ext.autodoc',
]

确保代码可以被导入¶

autodoc 通过 导入模块 后的内省来分析代码和docstrings。为了正确导入，您必须确保Sphinx可以找到您的模块并且可以解析依赖项（如果您的模块执行 import foo，但在运行Sphinx的Python环境中 foo 不可用，则您的模块导入将失败）。

有两种方法可以确保这一点：

使用包含您的软件包和Sphinx的环境。这可以是您的本地开发环境（有可编辑的安装实例），或者是在CI中的环境，在其中安装Sphinx和您的软件包。常规安装过程确保Sphinx可以找到您的软件包并且所有依赖项都可用。
或者，可以修补Sphinx运行，以便它可以直接在源代码上运行；例如，如果您想能够签出源代码、执行Sphinx构建。
- 在 conf.py 中修补 sys.path 以包含您的源路径。例如，如果您的存储库结构包含 doc/conf.py 并且您的软件包位于 src/my_package，则应将以下内容添加到您的 conf.py 中。
```
import sys
from pathlib import Path

sys.path.insert(0, str(Path('..', 'src').resolve()))
```
- 为了解决缺少的依赖项，请在 autodoc_mock_imports 设置中指定缺少的模块。

如何使用¶

现在，您可以使用指令为函数、类、模块等Python代码元素添加格式化的文档。例如，要记录函数 io.open()，从源文件读取其签名和docstring，您可以这样写：

.. autofunction:: io.open

您还可以使用自动指令的成员选项自动记录整个类甚至模块，例如：

.. automodule:: io
   :members:

小技巧

作为对autodoc扩展的提示，您可以在模块名称和对象名称之间放置 :: 分隔符，以便autodoc知道正确的模块（如果存在歧义）：

.. autoclass:: module.name::Noodle

将对象标记为公共或私有¶

如果某个成员的docstring在其信息字段列表中包含 :meta private: ，则autodoc将其视为私有成员。例如：
```
def my_function(my_arg, my_other_arg):
    """blah blah blah

    :meta private:
    """
```
在 3.0 版本加入.
如果某个成员的docstring在其信息字段列表中包含 :meta public: ，即使它以下划线开头，它也会认为它是公共的。例如：
```
def _my_function(my_arg, my_other_arg):
    """blah blah blah

    :meta public:
    """
```
在 3.1 版本加入.
如果某个变量成员的docstring在其信息字段列表中包含 :meta hide-value:，则autodoc认为该变量成员没有任何默认值。示例：
```
var1 = None  #: :meta hide-value:
```
在 3.5 版本加入.

文档注释和文档字符串¶

Python本身不支持为模块数据成员或类属性编写文档字符串。为了允许记录这些内容，autodoc 识别一种称为“文档注释”或“文档评论”的特殊格式的 comment 。

这些注释以冒号和可选的空格字符 '#:' 或 '#: ' 开头。要被识别，注释必须出现在与变量相同的行上，或者出现在变量之前的一行或多行上。多行文档注释必须始终出现在变量定义之前的行上。

例如，以下三个变量都有有效的文档注释：

egg_and_spam = 1.50  #: A simple meal

#: Spam! Lovely spam! Lovely spam!
egg_bacon_sausage_and_spam = 2.49

#: Truly gourmet cuisine for madam; Lobster Thermidor
#: aux Crevettes with a mornay sauce garnished with
#: truffle pate, brandy and a fried egg on top and spam.
lobster_thermidor = 35.00

或者，autodoc 可以识别紧跟定义之后的行上的docstring。

在以下类定义中，所有属性都有 autodoc 识别的文档：

class Foo:
    """Docstring for class Foo."""

    #: Doc comment for class attribute Foo.bar.
    #: It can have multiple lines.
    bar = 1

    flox = 1.5   #: Doc comment for Foo.flox. One line only.

    baz = 2
    """Docstring for class attribute Foo.baz."""

    def __init__(self):
        #: Doc comment for instance attribute qux.
        self.qux = 3

        self.spam = 4
        """Docstring for instance attribute spam."""

指令¶

autodoc 提供了几个通常的 py:module、py:class 等指令的版本。在解析时，它们导入相应的模块并提取给定对象的docstring，将它们插入到页面源中，位于合适的 py:module、py:class 等指令下。

备注

正如 py:class 尊重当前的 py:module 一样，autoclass 也会这样做。同样，automethod 将尊重当前的 py:class 。

默认指令选项¶

要使下面描述的任何选项成为默认选项，请在 conf.py 中使用 autodoc_default_options。

如果为 :members:、 :exclude-members:、 :private-members: 或 :special-members: 选项使用默认值，则在指令上设置该选项将覆盖默认值。相反，要使用每个指令选项扩展默认列表，该列表可以以加号（+）开头，如下所示：

.. autoclass:: Noodle
   :members: eat
   :private-members: +_spicy, _garlickly

小技巧

如果使用 autodoc_default_options，则可以通过否定形式 :no-option: 作为指令的选项来禁用每个指令的默认值。例如：

.. automodule:: foo
   :no-undoc-members:

自动为模块编写文档¶

.. automodule::¶

记录一个模块。默认情况下，该指令仅插入模块本身的docstring：

.. automodule:: noodles

将生成如下源代码：

.. py:module:: noodles

   The noodles module.

该指令还可以包含自己的内容，这些内容将在生成的非自动指令源代码中插入docstring之后（但在任何自动成员文档之前）。

因此，您还可以混合使用自动和非自动成员文档，如下所示：

.. automodule:: noodles
   :members: Noodle

   .. py:function:: boiled_noodle(time=10)

      Create a noodle that has been boiled for *time* minutes.

选项

:no-index:¶: 不为已记录的模块或任何自动记录的成员生成索引条目。

在 0.4 版本加入.

:no-index-entry:¶: 不为已记录的模块或任何自动记录的成员生成索引条目。与 :no-index: 不同，仍会创建交叉引用。

在 8.2 版本加入.

:platform: platforms (comma separated list)¶: 指示模块可用的平台。这与 py:module 的 :platform: 选项相同。

:synopsis: purpose (text)¶: 描述模块用途的句子。这与 py:module 的 :synopsis: 选项相同。

在 0.5 版本加入.

:deprecated:¶: 将模块标记为已弃用。这与 py:module 的 :deprecated: 选项相同。

在 0.5 版本加入.

:ignore-module-all: (no value)¶: 在分析要记录的模块时不要使用 __all__ 。

在 1.7 版本加入.

选择要记录的成员的选项

:members: (no value or comma separated list)¶

为目标模块的所有成员生成自动文档：

.. automodule:: noodles
   :members:

默认情况下，autodoc 仅包含具有docstring或 doc-comment （#:）的公共成员。如果存在 __all__，则将使用它来定义哪些成员是公共的，除非设置了 :ignore-module-all: 选项。

要仅记录某些成员，可以将显式的逗号分隔列表用作 :members: 的参数：

.. automodule:: noodles
   :members: Noodle

:exclude-members: (comma separated list)¶

从要记录的成员中排除给定的名称。例如：

.. automodule:: noodles
   :members:
   :exclude-members: NoodleBase

在 0.6 版本加入.

:imported-members: (no value)¶

为了防止记录导入的类或函数，在设置了 members 选项的 automodule 指令中，只有 __module__ 属性等于传递给 automodule 的模块名称的模块成员才会被记录。

如果要防止此行为并记录所有可用成员，请设置 imported-members 选项。

请注意，不会记录来自导入模块的属性，因为属性文档是通过解析当前模块的源文件来发现的。

在 1.2 版本加入.

:undoc-members:¶

为目标模块中没有docstring或doc-comment的成员生成自动文档。例如：

.. automodule:: noodles
   :members:
   :undoc-members:

:private-members: (no value or comma separated list)¶

为目标模块的私有成员生成自动文档。这包括以单下划线开头的名称（例如 _private ）和那些使用 :meta private: 明确标记为私有的成员。

.. automodule:: noodles
   :members:
   :private-members:

要仅记录某些私有成员，可以将显式的逗号分隔列表用作 :private-members: 的参数：

.. automodule:: noodles
   :members:
   :private-members: _spicy, _garlickly

在 1.1 版本加入.

在 3.2 版本发生变更: 该选项现在可以采用逗号分隔的参数列表。

:special-members: (no value or comma separated list)¶

为目标模块的特殊成员生成自动文档，也称为 'dunder' names 。这包括所有用双下划线括起来的名称，例如 __special__ ：

.. automodule:: my.Class
   :members:
   :special-members:

要仅记录某些特殊成员，可以将显式的逗号分隔列表用作 :special-members: 的参数：

.. automodule:: noodles
   :members:
   :special-members: __version__

在 1.1 版本加入.

在 1.2 版本发生变更: 该选项现在可以采用逗号分隔的参数列表。

为已记录的成员设置选项

:member-order: (alphabetical, bysource, or groupwise)¶

选择自动记录的成员的排序方式（默认值： alphabetical ）。这将覆盖 autodoc_member_order 设置。

alphabetical：使用简单的字母顺序。
groupwise：按对象类型（类、函数等）分组，在组内使用字母顺序。
bysource：使用模块源代码中对象的顺序。可以使用 __all__ 变量来覆盖此顺序。

请注意，对于源代码顺序，该模块必须是具有可用源代码的Python模块。

在 0.6 版本加入.

在 1.0 版本发生变更: 支持 'bysource' 选项。

:show-inheritance: (no value)¶: 如果启用了 :members:，则为模块的所有成员启用 :show-inheritance: 选项。

在 0.4 版本加入.

自动为类或异常编写文档¶

.. autoclass::¶

.. autoexception::¶

记录一个类。对于异常类，优先使用 .. autoexception:: 。默认情况下，该指令仅插入类本身的docstring：

.. autoclass:: noodles.Noodle

将生成如下源代码：

.. py:class:: Noodle

   The Noodle class's docstring.

该指令还可以包含自己的内容，这些内容将在生成的非自动指令源代码中插入docstring之后（但在任何自动成员文档之前）。

因此，您还可以混合使用自动和非自动成员文档，如下所示：

.. autoclass:: noodles.Noodle
   :members: eat, slurp

   .. py:method:: boil(time=10)

      Boil the noodle for *time* minutes.

高级用法

可以使用常规语法覆盖显式记录的可调用对象（函数、方法、类）的签名，从而覆盖从内省获得的签名：
```
.. autoclass:: noodles.Noodle(type)

   .. automethod:: eat(persona)
```
如果方法的签名被修饰符隐藏，这很有用。

在 0.4 版本加入.

选项

:no-index:¶: 不为已记录的类或任何自动记录的成员生成索引条目。

在 0.4 版本加入.

:no-index-entry:¶: 不为已记录的类或任何自动记录的成员生成索引条目。与 :no-index: 不同，仍会创建交叉引用。

在 8.2 版本加入.

:class-doc-from: (class, init, or both)¶

选择将用于指令主体的docstring。这将覆盖 autoclass_content 的全局值。可能的值有：

class：仅使用类的docstring。可以使用 :members: 选项或 automethod 单独记录 __init__() 方法。
init：仅使用 __init__() 方法的docstring。
both：两者都使用，将 __init__() 方法的docstring 附加到类的docstring。

如果不存在 __init__() 方法或其docstring为空，autodoc 将尝试使用 __new__() 方法的docstring（如果存在且不为空）。

在 4.1 版本加入.

选择要记录的成员的选项

:members: (no value or comma separated list)¶

为目标类的所有成员生成自动文档：

.. autoclass:: noodles.Noodle
   :members:

默认情况下，autodoc 仅包含具有docstring或 doc-comment （#:）且是目标类属性（即非继承）的公共成员。

要仅记录某些成员，可以将显式的逗号分隔列表用作 :members: 的参数：

.. autoclass:: noodles.Noodle
   :members: eat, slurp

:exclude-members: (comma separated list)¶

从要记录的成员中排除给定的名称。例如：

.. autoclass:: noodles.Noodle
   :members:
   :exclude-members: prepare

在 0.6 版本加入.

:inherited-members: (comma separated list)¶

要为从基类继承的成员生成自动文档，请使用 :inherited-members: 选项：

.. autoclass:: noodles.Noodle
   :members:
   :inherited-members:

这可以与 :undoc-members: 选项结合使用，以为类的*所有*可用成员生成自动文档。

在 :inherited-members: 的参数中列出的类的成员将从自动文档中排除。如果未提供参数，则默认为 object，这意味着不会记录 object 类的成员。要包含这些成员，请使用 None 作为参数。

例如；如果您的类 MyList 派生自 list 类，并且您不想记录 list.__len__()，则应指定选项 :inherited-members: list 以避免记录list类的特殊成员。

备注

如果任何继承的成员对其docstring使用的格式不是reStructuredText，则可能会出现标记警告或错误。

在 0.3 版本加入.

在 3.0 版本发生变更: :inherited-members: 现在将基类的名称作为参数进行排除。

在 5.0 版本发生变更: 可以使用以逗号分隔的基类名称列表。

:undoc-members: (no value)¶

为目标类中没有docstring或doc-comment的成员生成自动文档。例如：

.. autoclass:: noodles.Noodle
   :members:
   :undoc-members:

:private-members: (no value or comma separated list)¶

为目标类的私有成员生成自动文档。这包括以单下划线开头的名称（例如 _private ）和那些使用 :meta private: 明确标记为私有的成员。

.. autoclass:: noodles.Noodle
   :members:
   :private-members:

要仅记录某些私有成员，可以将显式的逗号分隔列表用作 :private-members: 的参数：

.. autoclass:: noodles.Noodle
   :members:
   :private-members: _spicy, _garlickly

在 1.1 版本加入.

在 3.2 版本发生变更: 选项现在可以接受参数。

:special-members: (no value or comma separated list)¶

为目标类的特殊成员生成自动文档，也称为 'dunder' names 。这包括所有用双下划线括起来的名称，例如 __special__ ：

.. autoclass:: noodles.Noodle
   :members:
   :special-members:

要仅记录某些特殊成员，可以将显式的逗号分隔列表用作 :special-members: 的参数：

.. autoclass:: noodles.Noodle
   :members:
   :special-members: __init__, __name__

在 1.1 版本加入.

在 1.2 版本发生变更: 该选项现在可以采用逗号分隔的参数列表。

为已记录的成员设置选项

:member-order: (alphabetical, bysource, or groupwise)¶

选择自动记录的成员的排序方式（默认值： alphabetical ）。这将覆盖 autodoc_member_order 设置。

'alphabetical'：使用简单的字母顺序。
'groupwise'：按对象类型（类、函数等）分组，在组内使用字母顺序。
'bysource'：使用模块源代码中对象的顺序。可以使用 __all__ 变量来覆盖此顺序。

请注意，对于源代码顺序，该模块必须是具有可用源代码的Python模块。

在 0.6 版本加入.

在 1.0 版本发生变更: 支持 'bysource' 选项。

:show-inheritance: (no value)¶: 在类签名后插入类的基类。

在 0.4 版本加入.

自动为类似函数的对象编写文档¶

.. autofunction::¶

.. automethod::¶

.. autoproperty::¶

.. autodecorator::¶

记录一个函数、方法、属性或修饰符。默认情况下，该指令仅插入函数本身的docstring：

.. autofunction:: noodles.average_noodle

将生成如下源代码：

.. py:function:: noodles.average_noodle

   The average_noodle function's docstring.

该指令还可以包含自己的内容，这些内容将在生成的非自动指令源代码中插入docstring之后。

因此，您还可以混合使用自动和非自动文档，如下所示：

.. autofunction:: noodles.average_noodle

   .. note:: For more flexibility, use the :py:class:`!Noodle` class.

在 2.0 版本加入: autodecorator。

在 2.1 版本加入: autoproperty。

备注

如果您记录了装饰过的函数或方法，请记住，autodoc 通过导入模块并检查给定函数或方法的 __doc__ 属性来检索其docstring。这意味着如果修饰符用另一个函数替换了被修饰的函数，则它必须将原始 __doc__ 复制到新函数中。

高级用法

可以使用常规语法覆盖显式记录的可调用对象（函数、方法、类）的签名，从而覆盖从内省获得的签名：
```
.. autoclass:: Noodle(type)

   .. automethod:: eat(persona)
```
如果方法的签名被修饰符隐藏，这很有用。

在 0.4 版本加入.

选项

:no-index:¶: 不为已记录的函数生成索引条目。

在 0.4 版本加入.

:no-index-entry:¶: 不为已记录的函数生成索引条目。与 :no-index: 不同，仍会创建交叉引用。

在 8.2 版本加入.

自动为属性或数据编写文档¶

.. autodata::¶

.. autoattribute::¶

记录模块级变量或常量（“数据”）或类属性。默认情况下，该指令仅插入变量本身的docstring：

.. autodata:: noodles.FLOUR_TYPE

将生成如下源代码：

.. py:data:: noodles.FLOUR_TYPE

   The FLOUR_TYPE constant's docstring.

该指令还可以包含自己的内容，这些内容将在生成的非自动指令源代码中插入docstring之后。

因此，您还可以混合使用自动和非自动成员文档，如下所示：

.. autodata:: noodles.FLOUR_TYPE

   .. hint:: Cooking time can vary by which flour type is used.

在 0.6 版本发生变更: autodata and autoattribute can now extract docstrings.

在 1.1 版本发生变更: 现在允许在赋值的同一行上使用文档注释。

选项

:no-index:¶: 不为已记录的变量或常量生成索引条目。

在 0.4 版本加入.

:no-index-entry:¶: 不为已记录的变量或常量生成索引条目。与 :no-index: 不同，仍会创建交叉引用。

在 8.2 版本加入.

:annotation: value (string)¶

在 1.2 版本加入.

默认情况下，autodoc 尝试通过内省获取变量的类型注释和值，并在变量名称后显示它。要覆盖此内容，可以将变量值的自定义字符串用作 annotation 的参数。

例如，如果 FILE_MODE 的运行时值为 0o755，则显示的值将为 493 （因为 oct(493) == '0o755'）。可以通过设置 :annotation: = 0o755 来解决此问题。

如果使用 :annotation: 而不带参数，则不会为变量显示任何值或类型提示。

:no-value:¶: 在 3.4 版本加入.

要显示变量的类型提示而不显示值，请使用 :no-value: 选项。如果同时使用了 :annotation: 和 :no-value: 选项，则 :no-value: 无效。

自动为类型别名编写文档¶

.. autotype::¶

在 9.0 版本加入.

记录一个 PEP 695 类型别名（type 语句）。默认情况下，该指令仅插入别名本身的docstring：

该指令还可以包含自己的内容，这些内容将在生成的非自动指令源代码中插入docstring之后（但在任何自动成员文档之前）。

因此，您还可以混合使用自动和非自动成员文档。

选项

:no-index:¶: 不为已记录的类或任何自动记录的成员生成索引条目。

:no-index-entry:¶: 不为已记录的类或任何自动记录的成员生成索引条目。与 :no-index: 不同，仍会创建交叉引用。

配置¶

您还可以设置配置值：

autodoc_use_legacy_class_based¶

类型:: bool
默认:: False

如果为真，autodoc 将使用传统的基于类的实现。这是 Sphinx 9.0 之前的行为。它基于 Documenter 类层次结构。

如果您的文档或您使用的扩展在Python代码中使用或猴子补丁传统的基于类的API，则提供此设置以实现向后兼容性。如果是这种情况，请在您的 conf.py 中将 autodoc_use_legacy_class_based = True 。并且请在 the tracking issue on GitHub 上添加评论，以便维护人员了解您的用例，以便将来可能进行改进。

备注

传统的基于类的实现不支持 PEP 695 类型别名。

autoclass_content¶

类型:: str
默认:: 'class'

此值选择将插入到主体的内容 autoclass 指令。可能的值为：

'class': 只插入类的docstring。您仍然可以使用 automethod 或 autoclass 的 members 选项将 __init__ 作为单独的方法进行记录。
'both': 类和方法的文档字符串都被连接并插入。
'init': 只插入 __init__ 方法的文档字符串。

在 0.3 版本加入.

如果类没有 __init__ 方法，或者 __init__ 方法的文档字符串为空，但该类有一个 __new__ 方法的文档字符串，则改用它。

在 1.4 版本加入.

autodoc_class_signature¶

类型:: str
默认:: 'mixed'

此值选择如何显示由 autoclass 指令定义的类的签名。可能的值为：

'mixed': 显示带有类名的签名。
'separated': 将签名显示为方法。

在 4.1 版本加入.

autodoc_member_order¶

类型:: str
默认:: 'alphabetical'

定义列出 automodule 和 autoclass 成员的顺序。支持的值有：

'alphabetical'：使用字母顺序。
'groupwise'：按成员类型排序。顺序为：
- 对于模块、异常、类、函数、数据
- 对于类：类方法、静态方法、方法，
  和 properties/attributes
成员在组内按字母顺序排列。
bysource：使用成员在源代码中出现的顺序。这要求模块必须是具有可用源代码的Python模块。

在 0.6 版本加入.

在 1.0 版本发生变更: 支持 'bysource'。

autodoc_default_options¶

类型:: dict[str, str | bool]
默认:: {}

自动文档指令的默认选项。它们会自动应用于所有自动文档指令。它必须是一个将选项名称映射到值的字典。例如：

autodoc_default_options = {
    'members': 'var1, var2',
    'member-order': 'bysource',
    'special-members': '__init__',
    'undoc-members': True,
    'exclude-members': '__weakref__'
}

将 None 或 True 设置为值相当于只给指令指定选项名。

支持的选项有：

'members'：见 automodule:members。
'undoc-members' 见 automodule:undoc-members。
'private-members'：见 automodule:private-members。
'special-members'：见 automodule:special-members。
'inherited-members'：见 autoclass:inherited-members。
'imported-members'：见 automodule:imported-members。
'exclude-members'：见 automodule:exclude-members。
'ignore-module-all'：见 automodule:ignore-module-all。
'member-order'：见 automodule:member-order。
'show-inheritance'：见 autoclass:show-inheritance。
'class-doc-from'：见 autoclass:class-doc-from。
'no-value'：见 autodata:no-value。
'no-index'：见 automodule:no-index。
'no-index-entry'：见 automodule:no-index-entry。

在 1.8 版本加入.

在 2.0 版本发生变更: 接受 True 作为值。

在 2.1 版本发生变更: 添加 'imported-members'.

在 4.1 版本发生变更: 添加 'class-doc-from'。

在 4.5 版本发生变更: 添加 'no-value'。

autodoc_docstring_signature¶

类型:: bool
默认:: True

从C模块导入的函数不能自省，因此不能自动确定这些函数的签名。但是，将签名放入函数的文档字符串的第一行是一个常用的约定。

如果此布尔值设置为 True （默认值），自动文档将查看文档字符串的第一行以查找函数和方法，如果它看起来像签名，则使用该行作为签名，并将其从文档字符串内容中删除。

autodoc 将继续查找多个签名行，在第一个看起来不像签名的行处停止。这对于声明重载函数签名很有用。

在 1.1 版本加入.

在 3.1 版本发生变更: 支持重载签名

在 4.0 版本发生变更: 重载签名不需要用反斜杠分隔

autodoc_mock_imports¶

类型:: list[str]
默认:: []

此值包含要模拟的模块列表。当某些外部依赖项在构建时不满足并中断构建过程时，这很有用。只能指定依赖项本身的根包，而忽略子模块：

autodoc_mock_imports = ['django']

将模拟 django 包下的所有导入。

在 1.3 版本加入.

在 1.6 版本发生变更: 这个配置值只需要声明应该模拟的顶层模块。

autodoc_typehints¶

类型:: str
默认:: 'signature'

此值控制如何表示类型提示。该设置采用以下值：

'signature' --在签名中显示类型提示
'description' -- 将类型提示显示为函数或方法的内容。重载函数或方法的类型提示仍将表示在签名中。
'none' -- 不显示类型提示
'both' -- 在签名中显示类型提示，并作为函数或方法的内容

重载的函数或方法不会在描述中包含类型提示，因为不可能将所有可能的重载准确地表示为参数列表。

在 2.1 版本加入.

在 3.0 版本加入: 添加了新选项 'description'。

在 4.1 版本加入: 添加了新选项 'both'。

autodoc_typehints_description_target¶

类型:: str
默认:: 'all'

此值控制在 autodoc_typehints 设置为 'description' 时，是否记录未记录的参数和返回值的类型。支持的值：

'all'：记录所有参数和返回值的类型，无论它们是否被记录。
'documented'：仅记录已由docstring记录的参数或返回值的类型。
'documented_params'：仅当参数在docstring中记录时，才会注释参数类型。返回类型始终被注释（除非它是 None）。

在 4.0 版本加入.

在 5.0 版本加入: 添加了新选项 'documented_params'。

autodoc_type_aliases¶

类型:: dict[str, str]
默认:: {}

用户定义的 type aliases 的字典，将类型名称映射到完全限定的对象名称。它用于在文档中保留未评估的类型别名。

只有当您的程序通过 from __future__ import annotations 启用 Postponed Evaluation of Annotations (PEP 563) 功能时，类型别名才可用。

例如，有使用类型别名的代码：

from __future__ import annotations

AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]

def f() -> AliasType:
    ...

如果 autodoc_type_aliases 未设置，autodoc 将根据以下代码生成内部标记：

.. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]

   ...

如果将 autodoc_type_aliases 设置为 {'AliasType': 'your.module.AliasType'}，则它在内部生成以下文档：

.. py:function:: f() -> your.module.AliasType:

   ...

在 3.3 版本加入.

autodoc_typehints_format¶

类型:: str
默认:: 'short'

此值控制类型提示的格式。该设置采用以下值：

'fully-qualified' -- 显示类型提示的模块名称及其名称
'short' -- 抑制类型提示的前导模块名称（例如 io.StringIO -> StringIO）

在 4.4 版本加入.

在 5.0 版本发生变更: 默认设置更改为 'short'

autodoc_preserve_defaults¶

类型:: bool
默认:: False

如果为True，则在生成文档时不会评估函数的默认参数值。它将它们保留在源代码中。

在 4.0 版本加入: 作为实验性功能添加。将来这将集成到autodoc核心中。

autodoc_use_type_comments¶

类型:: bool
默认:: True

如果为True，则尝试从源代码中读取 # type: ... 注释以补充缺失的类型注释。

如果您的源代码不使用类型注释（例如，如果它专门使用类型注释或不使用任何类型提示），则可以禁用此功能。

在 8.2 版本加入: 通过新的 autodoc_use_type_comments 选项添加了禁用使用类型注释的选项，出于向后兼容性的考虑，默认为 True。默认值将在 Sphinx 10 中更改为 False。

autodoc_warningiserror¶

类型:: bool
默认:: True

这个值控制导入模块期间 sphinx-build --fail-on-warning 的行为。如果给出 False，当导入的模块发出警告时，autodoc 会强制抑制错误。

在 8.1 版本发生变更: 由于 --fail-on-warning 不再提前退出，因此此选项现在无效。

autodoc_inherit_docstrings¶

类型:: bool
默认:: True

此值控制docstrings继承。如果设置为True，则类或方法的docstring（如果未显式设置）将从父级继承。

在 1.7 版本加入.

suppress_warnings

类型:: Sequence[str]
默认:: ()

autodoc 支持通过 suppress_warnings 抑制警告消息。它定义了以下其他警告类型：

autodoc
autodoc.import_object

文档字符串预处理¶

自动文档提供如下额外事件

autodoc-process-docstring(app, obj_type, name, obj, options, lines)¶

在 0.4 版本加入.

当自动文档读取并处理文档字符串时发出。lines 是一个字符串列表，即已处理的文档字符串的行，事件处理程序可以就地修改以更改Sphinx在输出中的内容。

参数:

app -- sphinx应用目标
obj_type -- 文档字符串所属对象的类型（'module'、'class'、'exception'、'function'、'decorator'、'method'、'property'、'attribute'、'data' 或 'type' 之一）
name -- 对象的完全限定名
obj -- 对象自身
options -- 指令给出的选项：一个对象，其属性对应于自动指令中使用的选项，例如 inherited_members、undoc_members 或 show_inheritance。
lines -- 文档字符串的行，见上文

autodoc-before-process-signature(app, obj, bound_method)¶

在 2.4 版本加入.

在autodoc格式化对象的签名之前发出。事件处理程序可以修改对象以更改其签名。

参数:

app -- sphinx应用目标
obj -- 对象自身
bound_method -- 布尔值表示对象是否是绑定方法

autodoc-process-signature(app, obj_type, name, obj, options, signature, return_annotation)¶

在 0.5 版本加入.

当自动文档已格式化对象的签名时发出。事件处理程序可以返回一个新的元组 (signature, return_annotation) 来更改Sphinx在输出中的内容。

参数:

app -- sphinx应用目标
obj_type -- 文档字符串所属对象的类型（'module'、'class'、'exception'、'function'、'decorator'、'method'、'property'、'attribute'、'data' 或 'type' 之一）
name -- 对象的完全限定名
obj -- 对象自身
options -- 指令给出的选项：一个对象，其属性对应于自动指令中使用的选项，例如 inherited_members、undoc_members 或 show_inheritance。
signature -- 函数签名，形式为 '(parameter_1, parameter_2)' 的字符串，如果自省未成功且未在指令中指定签名，则为 None。
return_annotation -- 函数返回注释，形式为 'annotation' 的字符串，如果没有返回注释，则为 ''。

sphinx.ext.autodoc 模块提供工厂函数，给事件 autodoc-process-docstring 提供通用的docstring 处理:

sphinx.ext.autodoc.cut_lines(pre: int, post: int = 0, what: Sequence[str] | None = None) → _AutodocProcessDocstringListener[源代码]¶

返回一个侦听器，它删除每个文档字符串的第一行 pre 行和最后一行 post。如果 what 是字符串序列，则只处理 what 中类型的文档字符串。

像这样使用（例如在 conf.py 的 setup() 函数中):

from sphinx.ext.autodoc import cut_lines

app.connect('autodoc-process-docstring', cut_lines(4, what={'module'}))

这可以（也应该）代替 automodule_skip_lines。

sphinx.ext.autodoc.between(marker: str, what: Sequence[str] | None = None, keepempty: bool = False, exclude: bool = False) → _AutodocProcessDocstringListener[源代码]¶

返回一个侦听器，该侦听器保留或如果 exclude 为真，则排除与 marker 正则表达式匹配的行之间的行。如果没有行匹配，则生成的文档字符串将为空，因此除非 keepmpty 为真，否则不会进行任何更改。

如果 what 是字符串序列，则只处理 what 中类型的文档字符串。

autodoc-process-bases(app, name, obj, _unused, bases)¶

当自动文档读取并处理类以确定基类时发出。bases 是类的列表，事件处理程序可以就地修改以更改Sphinx在输出中的内容。仅当给出 show-inheritance 选项时才发出。

参数:

app -- sphinx应用目标
name -- 对象的完全限定名
obj -- 对象自身
_unused -- 未使用的占位符
bases -- 基类签名列表。见上文。

在 4.1 版本加入.

在 4.3 版本发生变更: bases 可以包含作为基类名称的字符串。它将被处理为 reStructuredText。

跳过成员¶

自动文档允许用户定义一个自定义方法，通过使用以下事件确定是否应将成员包括在文档中：

autodoc-skip-member(app, obj_type, name, obj, skip, options)¶

在 0.5 版本加入.

当自动文档必须决定是否应将成员包含在文档中时发出。如果处理程序返回“True”，则排除该成员。如果处理程序返回“False”，则会包含此函数。

如果多个已启用的扩展处理 autodoc-skip-member 事件，autodoc 将使用处理程序返回的第一个非“None”值。处理程序应返回“None”以返回自动文档和其他已启用扩展的跳过行为。

参数:

app -- sphinx应用目标
obj_type -- 文档字符串所属对象的类型（'module'、'class'、'exception'、'function'、'decorator'、'method'、'property'、'attribute'、'data' 或 'type' 之一）
name -- 对象的完全限定名
obj -- 对象自身
skip -- 一个布尔值，指示如果用户处理程序不重写决策，自动文档是否将跳过此成员
options -- 指令给出的选项：一个对象，其属性对应于自动指令中使用的选项，例如 inherited_members、undoc_members 或 show_inheritance。

sphinx.ext.autodoc -- 纳入来自docstrings的文档¶

开始¶

设置¶

确保代码可以被导入¶

如何使用¶

将对象标记为公共或私有¶

文档注释和文档字符串¶

指令¶

默认指令选项¶

自动为模块编写文档¶

自动为类或异常编写文档¶

自动为类似函数的对象编写文档¶

自动为属性或数据编写文档¶

自动为类型别名编写文档¶

配置¶

文档字符串预处理¶

跳过成员¶

`sphinx.ext.autodoc` -- 纳入来自docstrings的文档¶