`sphinx.ext.autodoc` – 从 docstrings 中包含文档¶

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

警告

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

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

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

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

入门¶

设置¶

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

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

确保代码可以导入¶

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

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

使用包含您的包和 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()，从源文件中读取其签名和文档字符串，您可以这样写

.. 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 识别一种特殊格式的注释，称为“文档注释”或“文档注释”。

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

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

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

:synopsis: 目的（文本）¶: 描述模块目的的句子。这与 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：只使用类的文档字符串。可以使用 :members: 选项或 automethod 单独文档 __init__() 方法。
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: 值（字符串）¶

版本 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 语句）。默认情况下，指令只插入别名本身的文档字符串

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

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

选项

:no-index:¶: 不要为文档化的类或任何自动文档化的成员生成索引条目。

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

配置¶

还有一些可以设置的配置值

autodoc_use_legacy_class_based¶

类型:: bool
默认:: False

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

此设置用于向后兼容，如果您的文档或您使用的扩展在 Python 代码中使用了或猴子补丁了旧版基于类的 API。如果是这种情况，请在您的 conf.py 中设置 autodoc_use_legacy_class_based = True。另请在 GitHub 上的跟踪问题中添加评论，以便维护人员了解您的用例，以备未来可能的改进。

注意

旧版基于类的实现不支持 PEP 695 类型别名。

autoclass_content¶

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

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

'class': 只插入类的文档字符串。您仍然可以使用 automethod 或 autoclass 的 members 选项将 __init__ 作为单独的方法文档。
'both': 类的文档字符串和 __init__ 方法的文档字符串都连接并插入。
'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'：按成员类型排序。顺序为
- 适用于模块、异常、类、函数、数据
- 对于类：类方法、静态方法、方法、
  和属性/特性
成员在组内按字母顺序排序。
'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 新增。

禁止_警告

类型:: 序列[str]
默认:: ()

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

autodoc
autodoc.import_object

文档字符串预处理¶

autodoc 提供以下附加事件

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

版本 0.4 新增。

当 autodoc 读取并处理文档字符串时触发。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 和 no-index 属性的对象，如果自动指令给定同名标志选项，则这些属性为 True
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 中新增。

当 autodoc 格式化对象的签名后触发。事件处理程序可以返回一个新的元组 (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 和 no-index 属性的对象，如果自动指令给定同名标志选项，则这些属性为 True
signature – 函数签名，形如 '(parameter_1, parameter_2)' 的字符串，如果内省不成功且指令中未指定签名，则为 None。
return_annotation – 函数返回注释，形如 'annotation' 的字符串，如果没有返回注释，则为 ''。

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, _unused, bases)¶

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

参数:

app – Sphinx 应用程序对象
name – 对象的完全限定名
obj – 对象本身
_unused – 未使用的占位符
bases – 基类签名列表。见上文。

版本 4.1 新增。

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

跳过成员¶

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

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

版本 0.5 中新增。

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

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

参数:

app – Sphinx 应用程序对象
obj_type – 文档字符串所属对象的类型（'module'、'class'、'exception'、'function'、'decorator'、'method'、'property'、'attribute'、'data' 或 'type' 之一）
name – 对象的完全限定名
obj – 对象本身
skip – 一个布尔值，指示如果用户处理程序不覆盖决定，autodoc是否会跳过此成员
options – 给定指令的选项：一个具有 inherited_members、undoc_members、show_inheritance 和 no-index 属性的对象，如果自动指令给定同名标志选项，则这些属性为 True

sphinx.ext.autodoc – 从 docstrings 中包含文档¶

入门¶

设置¶

确保代码可以导入¶

用法¶

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

文档注释和文档字符串¶

指令¶

默认指令选项¶

自动文档模块¶

自动文档类或异常¶

自动文档函数类对象¶

自动文档属性或数据¶

自动文档类型别名¶

配置¶

文档字符串预处理¶

跳过成员¶

`sphinx.ext.autodoc` – 从 docstrings 中包含文档¶