`sphinx.ext.autodoc` – 从文档字符串中包含文档¶

此扩展可以导入您正在文档化的模块，并以半自动方式从文档字符串中提取文档。

警告

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

如果您要文档化脚本（而不是库模块），请确保主例程受到 if __name__ == '__main__' 条件的保护。

为了使其工作，文档字符串当然必须以正确的 reStructuredText 编写。然后，您可以在文档字符串中使用所有常用的 Sphinx 标记，它将正确地出现在文档中。与手写文档一起，此技术减轻了维护两个文档位置的痛苦，同时避免了自动生成外观的纯 API 文档。

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

开始¶

设置¶

通过将 'sphinx.ext.autodoc' 添加到 extensions 列表中的 conf.py 来激活插件

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

确保代码可以被导入¶

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

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

使用包含您的包和 Sphinx 的环境。例如，这可以是您的本地开发环境（带有可编辑安装），或者您在其中安装 Sphinx 和您的包的 CI 环境。常规安装过程确保 Sphinx 可以找到您的包，并且所有依赖项都可用。
或者，可以修补 Sphinx 运行，使其可以直接在源上操作；例如，如果您希望能够从源签出执行 Sphinx 构建。
- 修补 sys.path 在 conf.py 中以包含您的源路径。例如，如果您具有带有 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()，从源文件读取其签名和文档字符串，您可以编写

.. autofunction:: io.open

您还可以使用 auto 指令的成员选项自动文档化整个类甚至模块，例如

.. automodule:: io
   :members:

提示

作为对 autodoc 扩展的提示，您可以在模块名称和对象名称之间放置一个 :: 分隔符，以便在模块不明确时让 autodoc 知道正确的模块

.. autoclass:: module.name::Noodle

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

如果成员的文档字符串在其信息字段列表中包含 :meta private:，则 autodoc 认为该成员是私有的。例如
```
def my_function(my_arg, my_other_arg):
    """blah blah blah

    :meta private:
    """
```
在版本 3.0 中添加。
如果成员的文档字符串在其信息字段列表中包含 :meta public:，则 autodoc 认为该成员是公共的，即使它以下划线开头。例如
```
def _my_function(my_arg, my_other_arg):
    """blah blah blah

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

文档注释和文档字符串¶

Python 没有对模块数据成员或类属性的文档字符串的内置支持。为了允许文档化这些，autodoc 识别注释的特殊格式，称为“文档注释”或“documentation 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 可以识别紧跟在定义之后的行上的文档字符串。

在以下类定义中，所有属性都具有 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 等的版本。在解析时，它们导入相应的模块并提取给定对象的文档字符串，将其插入到页面源中，位于合适的 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::¶

文档模块。默认情况下，该指令仅插入模块本身的文档字符串

.. automodule:: noodles

将生成如下源代码

.. py:module:: noodles

   The noodles module.

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

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

.. 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 (逗号分隔列表)¶: 指示模块可用的平台。这与 py:module 的 :platform: 选项相同。

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

在版本 0.5 中添加。

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

在版本 0.5 中添加。

:ignore-module-all: (无值)¶: 在分析要文档化的模块时，不要使用 __all__。

在版本 1.7 中添加。

用于选择要文档化的成员的选项

:members: (无值或逗号分隔列表)¶

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

.. automodule:: noodles
   :members:

默认情况下，autodoc 仅包含带有文档字符串或文档注释 (#:) 的公共成员。如果 __all__ 存在，则将使用它来定义哪些成员是公共的，除非设置了 :ignore-module-all: 选项。

要仅文档化某些成员，可以使用显式的逗号分隔列表作为 :members: 的参数

.. automodule:: noodles
   :members: Noodle

:exclude-members: (逗号分隔列表)¶

从要文档化的成员中排除给定的名称。例如

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

在版本 0.6 中添加。

:imported-members: (无值)¶

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

如果您想防止此行为并文档化所有可用的成员，请设置 imported-members 选项。

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

在版本 1.2 中添加。

:undoc-members:¶

为目标模块中没有文档字符串或文档注释的成员生成自动文档。例如

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

:private-members: (无值或逗号分隔列表)¶

为目标模块的私有成员生成自动文档。这包括带有前导下划线的名称（例如 _private）以及那些使用 :meta private: 显式标记为私有的成员。

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

要仅文档化某些私有成员，可以使用显式的逗号分隔列表作为 :private-members: 的参数

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

在版本 1.1 中添加。

在版本 3.2 中更改: 该选项现在可以接受逗号分隔的参数列表。

:special-members: (无值或逗号分隔列表)¶

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

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

要仅文档化某些特殊成员，可以使用显式的逗号分隔列表作为 :special-members: 的参数

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

在版本 1.1 中添加。

在版本 1.2 中更改: 该选项现在可以接受逗号分隔的参数列表。

用于文档化成员的选项

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

选择自动文档化成员的顺序（默认值：alphabetical）。这会覆盖 autodoc_member_order 设置。

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

请注意，对于源代码顺序，模块必须是 Python 模块，并且源代码可用。

在版本 0.6 中添加。

在版本 1.0 中更改: 支持 'bysource' 选项。

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

在版本 0.4 中添加。

自动文档类或异常¶

.. autoclass::¶

.. autoexception::¶

文档类。对于异常类，首选 .. autoexception::。默认情况下，该指令仅插入类本身的文档字符串

.. autoclass:: noodles.Noodle

将生成如下源代码

.. py:class:: Noodle

   The Noodle class's 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, 或 both)¶

选择哪个文档字符串将用于指令的主体。这将覆盖 autoclass_content 的全局值。可能的值为

class：仅使用类的文档字符串。__init__() 方法可以使用 :members: 选项或 automethod 单独文档化。
init：仅使用 __init__() 方法的文档字符串。
both：同时使用两者，将 __init__() 方法的文档字符串附加到类的文档字符串。

如果 __init__() 方法不存在或具有空白文档字符串，则 autodoc 将尝试使用 __new__() 方法的文档字符串（如果存在且不为空白）。

在版本 4.1 中添加。

用于选择要文档化的成员的选项

:members: (无值或逗号分隔列表)¶

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

.. autoclass:: noodles.Noodle
   :members:

默认情况下，autodoc 仅包含带有文档字符串或文档注释 (#:) 且属于目标类属性（即未继承）的公共成员。

要仅文档化某些成员，可以使用显式的逗号分隔列表作为 :members: 的参数

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

:exclude-members: (逗号分隔列表)¶

从要文档化的成员中排除给定的名称。例如

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

在版本 0.6 中添加。

:inherited-members: (逗号分隔列表)¶

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

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

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

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

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

注意

如果任何继承的成员对其文档字符串使用 reStructuredText 以外的格式，则可能会出现标记警告或错误。

在版本 0.3 中添加。

在版本 3.0 中更改: :inherited-members: 现在接受要排除的基类的名称作为参数。

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

:undoc-members: (无值)¶

为目标类中没有文档字符串或文档注释的成员生成自动文档。例如

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

:private-members: (无值或逗号分隔列表)¶

为目标类的私有成员生成自动文档。这包括以下划线开头的名称 (例如，_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: (无值或逗号分隔列表)¶

为目标类的特殊成员生成自动文档，也称为 “dunder” 名称。这包括所有用双下划线括起来的名称，例如 __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, 或 groupwise)¶

选择自动文档化成员的顺序（默认值：alphabetical）。这会覆盖 autodoc_member_order 设置。

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

请注意，对于源代码顺序，模块必须是 Python 模块，并且源代码可用。

在版本 0.6 中添加。

在版本 1.0 中更改: 支持 'bysource' 选项。

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

在版本 0.4 中添加。

自动记录函数式对象¶

.. autofunction::¶

.. automethod::¶

.. autoproperty::¶

.. autodecorator::¶

记录函数、方法、属性或装饰器。默认情况下，该指令仅插入函数本身的文档字符串

.. autofunction:: noodles.average_noodle

将生成如下源代码

.. py:function:: noodles.average_noodle

   The average_noodle function's docstring.

该指令也可以包含自己的内容，这些内容将在文档字符串之后插入到生成的非自动指令源中。

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

.. autofunction:: noodles.average_noodle

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

在 2.0 版本中新增: autodecorator。

在 2.1 版本中新增: autoproperty。

注意

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

高级用法

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

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

在版本 0.4 中添加。

选项

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

在版本 0.4 中添加。

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

在版本 8.2 中添加。

自动记录属性或数据¶

.. autodata::¶

.. autoattribute::¶

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

.. autodata:: noodles.FLOUR_TYPE

将生成如下源代码

.. py:data:: noodles.FLOUR_TYPE

   The FLOUR_TYPE constant's docstring.

该指令也可以包含自己的内容，这些内容将在文档字符串之后插入到生成的非自动指令源中。

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

.. autodata:: noodles.FLOUR_TYPE

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

在 0.6 版本中变更: autodata 和 autoattribute 现在可以提取文档字符串。

在 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: 无效。

配置¶

您还可以设置以下配置值

autoclass_content¶

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

此值选择将哪些内容插入到 autoclass 指令的主体中。可能的值包括

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

在版本 0.3 中添加。

如果类没有 __init__ 方法，或者 __init__ 方法的文档字符串为空，但类具有 __new__ 方法的文档字符串，则将使用 __new__ 方法的文档字符串。

在 1.4 版本中新增。

autodoc_class_signature¶

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

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

'mixed': 使用类名显示签名。
'separated': 将签名显示为方法。

在版本 4.1 中添加。

autodoc_member_order¶

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

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

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

在版本 0.6 中添加。

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

autodoc_default_options¶

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

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

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 将查看函数和方法的文档字符串的第一行，如果它看起来像签名，则将该行用作签名并从文档字符串内容中删除它。

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': 类型将仅针对已通过文档字符串记录的参数或返回值进行记录。
'documented_params': 仅当参数在文档字符串中记录时，才会注释参数类型。返回值类型始终会被注释（除非它是 None）。

在 4.0 版本中新增。

在 5.0 版本中新增: 新增选项 'documented_params'。

autodoc_type_aliases¶

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

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

仅当您的程序通过 from __future__ import 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

此值控制文档字符串继承。如果设置为 True，则类或方法的文档字符串（如果未显式设置）将从父类继承。

在版本 1.7 中添加。

suppress_warnings

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

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

autodoc
autodoc.import_object

文档字符串预处理¶

autodoc 提供了以下附加事件

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

在版本 0.4 中添加。

当 autodoc 读取并处理文档字符串时发出。lines 是字符串列表 – 处理后的文档字符串的行 – 事件处理程序可以就地修改这些行，以更改 Sphinx 输出的内容。

参数:

app – Sphinx 应用程序对象
what – 文档字符串所属对象的类型（'module'、'class'、'exception'、'function'、'method'、'attribute' 之一）
name – 对象的完全限定名称
obj – 对象本身
options – 传递给指令的选项：一个对象，其属性 inherited_members、undoc_members、show_inheritance 和 no-index 在给定同名标志选项给 auto 指令时为 true
lines – 文档字符串的行，请参阅上文

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

在 2.4 版本中新增。

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

参数:

app – Sphinx 应用程序对象
obj – 对象本身
bound_method – 布尔值，指示对象是否为绑定方法

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

在版本 0.5 中添加。

当 autodoc 为对象格式化签名后发出。事件处理程序可以返回一个新的元组 (signature, return_annotation) 以更改 Sphinx 输出的内容。

参数:

app – Sphinx 应用程序对象
what – 文档字符串所属对象的类型（'module'、'class'、'exception'、'function'、'method'、'attribute' 之一）
name – 对象的完全限定名称
obj – 对象本身
options – 传递给指令的选项：一个对象，其属性 inherited_members、undoc_members、show_inheritance 和 no-index 在给定同名标志选项给 auto 指令时为 true
signature – 函数签名，格式为 '(parameter_1, parameter_2)' 的字符串，如果内省不成功且指令中未指定签名，则为 None。
return_annotation – 函数返回注释，格式为 ' -> annotation' 的字符串，如果没有返回注释，则为 None

sphinx.ext.autodoc 模块为事件 autodoc-process-docstring 中常用的文档字符串处理提供了工厂函数

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

返回一个监听器，该监听器移除每个文档字符串的开头 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[source]¶

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

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

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

当 autodoc 读取并处理一个类以确定基类时发出。bases 是一个类列表，事件处理程序可以就地修改该列表，以更改 Sphinx 放入输出的内容。仅当给定 show-inheritance 选项时才会发出。

参数:

app – Sphinx 应用程序对象
name – 对象的完全限定名称
obj – 对象本身
options – 传递给类指令的选项
bases – 基类签名列表。见上文。

在版本 4.1 中添加。

在版本 4.3 中更改: bases 可以包含一个字符串作为基类名称。它将被处理为 reStructuredText。

跳过成员¶

autodoc 允许用户使用以下事件定义一个自定义方法，用于确定是否应在文档中包含成员

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

在版本 0.5 中添加。

当 autodoc 必须决定是否应在文档中包含成员时发出。如果处理程序返回 True，则排除该成员。如果处理程序返回 False，则包含该成员。

如果多个启用的扩展处理 autodoc-skip-member 事件，则 autodoc 将使用处理程序返回的第一个非 None 值。处理程序应返回 None 以退回到 autodoc 和其他启用的扩展的跳过行为。

参数:

app – Sphinx 应用程序对象
what – 文档字符串所属对象的类型（'module'、'class'、'exception'、'function'、'method'、'attribute' 之一）
name – 对象的完全限定名称
obj – 对象本身
skip – 一个布尔值，指示如果用户处理程序不覆盖该决策，autodoc 是否将跳过此成员
options – 传递给指令的选项：一个对象，其属性 inherited_members、undoc_members、show_inheritance 和 no-index 在给定同名标志选项给 auto 指令时为 true

sphinx.ext.autodoc – 从文档字符串中包含文档¶

开始¶

设置¶

确保代码可以被导入¶

用法¶

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

文档注释和文档字符串¶

指令¶

默认指令选项¶

自动文档模块¶

自动文档类或异常¶

自动记录函数式对象¶

自动记录属性或数据¶

配置¶

文档字符串预处理¶

跳过成员¶

`sphinx.ext.autodoc` – 从文档字符串中包含文档¶