`sphinx.ext.autodoc` --包括文档字符串中的文档¶

该扩展可以导入您正在记录的模块，并以半自动的方式从文档字符串中拉入文档。

警告

autodoc imports the modules to be documented. If any modules have side effects on import, these will be executed by autodoc when sphinx-build is run.

如果您记录脚本（而不是库模块），请确保主例程受 if __name__ == '__main__' 条件

为了实现这一目标，文档字符串当然必须以正确的reStructured文本编写。然后，您可以在文档字符串中使用所有常见的Sphinx标记，并且它将在文档中正确地结束。与手写文档一起，该技术减轻了必须维护两个文档位置的痛苦，同时避免了自动生成的外观纯API文档。

如果您不希望 NumPy 或 Google 在reStructuredtext上样式文档字符串，您还可以启用 napoleon 扩展名. napoleon 是一个预处理器，可以将文档字符串转换为正确的reStructuredtext autodoc 处理它们。

入门¶

设置¶

通过添加激活插件 'sphinx.ext.autodoc' 到 extensions 列表 conf.py :

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

确保代码可以导入¶

autodoc 通过内省来分析代码和文档字符串 importing the modules .为了导入工作，您必须确保您的模块可以被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

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

.. automodule:: io
   :members:

小技巧

作为对autodoc扩展的提示，您可以将 :: 模块名称和对象名称之间的分隔符，如果不明确，则让autodoc知道正确的模块：

.. autoclass:: module.name::Noodle

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

如果其文档字符串包含，则AutoDoc将成员视为私有成员 :meta private: 在ITS中信息字段列表。例如：
```
def my_function(my_arg, my_other_arg):
    """blah blah blah

    :meta private:
    """
```
Added in version 3.0.
如果其文档字符串包含，则AutoDoc将成员视为公共成员 :meta public: 在ITS中信息字段列表，即使它以下划线开头。例如：
```
def _my_function(my_arg, my_other_arg):
    """blah blah blah

    :meta public:
    """
```
Added in version 3.1.
如果变量成员的文档字符串包含，则AutoDoc认为该变量成员没有任何默认值 :meta hide-value: 在ITS中信息字段列表。示例：
```
var1 = None  #: :meta hide-value:
```
Added in version 3.5.

文档注释和文档字符串¶

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

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

例如，以下三个变量都有有效的doc-comments：

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 .

默认指令选项¶

要将下面描述的任何选项设为默认选项，请使用 autodoc_default_options 字典 conf.py .

如果使用默认值 :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:¶: 不要为已记录的模块或任何自动记录的成员生成索引条目。

Added in version 0.4.

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

Added in version 8.2.

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

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

Added in version 0.5.

:deprecated:¶: 将模块标记为已废弃。这与 py:module 的 :deprecated: 选项.

Added in version 0.5.

:ignore-module-all: (no value)¶: 不要使用 __all__ 当分析模块以文档时。

Added in version 1.7.

选择要记录的成员的选项

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

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

.. automodule:: noodles
   :members:

By default, autodoc only includes public members with a docstring or doc-comment (#:). If __all__ exists, it will be used to define which members are public, unless the :ignore-module-all: option is set.

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

.. automodule:: noodles
   :members: Noodle

:exclude-members: (comma separated list)¶

将成员的姓名复制到文件中。例如：

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

Added in version 0.6.

:imported-members: (no value)¶

为了防止对导入的类或函数进行文档，请在 automodule 指令 members 选项集，仅限模块成员， __module__ 属性等于赋予的模块名称 automodule 将被记录下来。

设置 imported-members 如果您想防止此行为并记录所有可用成员，则可以使用该选项。

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

Added in version 1.2.

:undoc-members:¶

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

.. 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

Added in version 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__

Added in version 1.1.

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

有记录的成员的选项

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

选择自动记录成员的顺序（默认： alphabetical ).这将覆盖 autodoc_member_order 设置.

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

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

Added in version 0.6.

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

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

Added in version 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)
```
如果来自该方法的签名被装饰符隐藏，则这很有用。

Added in version 0.4.

选项

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

Added in version 0.4.

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

Added in version 8.2.

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

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

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

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

Added in version 4.1.

选择要记录的成员的选项

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

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

.. autoclass:: noodles.Noodle
   :members:

By default, autodoc only includes public members with a docstring or doc-comment (#:) that are attributes of the target class (i.e. not inherited).

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

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

:exclude-members: (comma separated list)¶

将成员的姓名复制到文件中。例如：

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

Added in version 0.6.

:inherited-members: (comma separated list)¶

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

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

这可以与 :undoc-members: 可选择生成自动文档 all 班级的可用成员。

论点中列出的班级成员 :inherited-members: 被排除在自动文档之外。其默认值为 object 如果没有提供参数，这意味着成员 object 类没有记录。要包含这些，请使用 None as the argument参数.

例如;如果您的班级 MyList 来源于 list 类并且您不想记录 list.__len__() ，您应该指定一个选项 :inherited-members: list 以避免列表类的特殊成员。

备注

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

Added in version 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

Added in version 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__

Added in version 1.1.

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

有记录的成员的选项

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

选择自动记录成员的顺序（默认： alphabetical ).这将覆盖 autodoc_member_order 设置.

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

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

Added in version 0.6.

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

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

Added in version 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.

Added in version 2.0: autodecorator .

Added in version 2.1: autoproperty .

备注

如果您记录装饰的函数或方法，请记住 autodoc 通过导入模块并检查 __doc__ 给定函数或方法的属性。这意味着如果装饰者用另一个替换装饰过的函数，则必须复制原始的 __doc__ 到新功能。

高级用法

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

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

Added in version 0.4.

选项

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

Added in version 0.4.

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

Added in version 8.2.

自动记录属性或数据¶

.. autodata::¶

.. autoattribute::¶

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

.. 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:¶: 不要为文档化的变量或常量生成索引项。

Added in version 0.4.

:no-index-entry:¶: 不要为文档化的变量或常量生成索引项。不像 :no-index: ，仍然创建交叉引用。

Added in version 8.2.

:annotation: value (string)¶

Added in version 1.2.

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

例如，如果的运行时值 FILE_MODE 是 0o755 ，显示的值将是 493 （作为 oct(493) == '0o755' ).这可以通过设置来修复 :annotation: = 0o755 .

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

:no-value:¶: Added in version 3.4.

要显示不带值的变量的类型提示，请使用 :no-value: 选项.如果两个 :annotation: 和 :no-value: 使用选项， :no-value: 没有效果。

配置¶

您还可以设置以下配置值：

autoclass_content¶

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

该值选择将哪些内容插入到 autoclass 指令。可能的值包括：

'class': 仅插入类的文档字符串。您仍然可以记录 __init__ 作为一种单独的方法， automethod 或 members 选项 autoclass .
'both': 无论是班级的还是 __init__ 方法的文档字符串连接并插入。
'init': 只有 __init__ 方法的文档字符串被插入。

Added in version 0.3.

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

Added in version 1.4.

autodoc_class_signature¶

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

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

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

Added in version 4.1.

autodoc_member_order¶

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

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

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

Added in version 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 .

Added in version 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将继续查找多个签名行，并在看起来不像签名的第一行停止。这对于声明重载函数签名很有用。

Added in version 1.1.

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

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

autodoc_mock_imports¶

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

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

autodoc_mock_imports = ['django']

将模拟所有 django 包裹。

Added in version 1.3.

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

autodoc_typehints¶

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

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

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

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

Added in version 2.1.

Added in version 3.0: 新选项 'description' 已添加。

Added in version 4.1: 新选项 'both' 已添加。

autodoc_typehints_description_target¶

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

此值控制在以下情况下是否记录未记录参数和返回值的类型 autodoc_typehints 设置为 'description' .支持的价值观：

'all' ：所有参数和返回值的类型都被记录，无论是否被记录。
'documented' ：仅为文档字符串已记录的参数或返回值记录类型。
'documented_params' ：只有当参数记录在文档字符串中时，才会注释参数类型。返回类型始终带有注释（除非是 None ).

Added in version 4.0.

Added in version 5.0: 新选项 'documented_params' 已添加。

autodoc_type_aliases¶

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

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

类型别名仅在您的程序启用 Postponed Evaluation of Annotations (PEP 563) 功能通过 from __future__ import annotations 。

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

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:

   ...

Added in version 3.3.

autodoc_typehints_format¶

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

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

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

Added in version 4.4.

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

autodoc_preserve_defaults¶

类型:: bool
默认:: False

如果为True，则在生成文档时不计算函数的默认参数值。它按源代码中的原样保留它们。

Added in version 4.0: 作为试验性功能添加。这将在未来集成到AutoDoc核心中。

autodoc_use_type_comments¶

类型:: bool
默认:: True

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

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

Added in version 8.2: 添加了通过新的禁用类型评论的选项 autodoc_use_type_comments 选项，默认为 True 用于向后兼容性。默认值将更改为 False 狮身克斯10。

autodoc_warningiserror¶

类型:: bool
默认:: True

此值控制的行为 sphinx-build --fail-on-warning 在导入模块期间。如果 False 则如果导入的模块发出警告，autodoc将强制抑制该错误。

在 8.1 版本发生变更: 该选项现在没有效果， --fail-on-warning 不再提前退出。

autodoc_inherit_docstrings¶

类型:: bool
默认:: True

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

Added in version 1.7.

suppress_warnings

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

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

自动对接
autodoc.import_object

文档字符串预处理¶

AutoDoc提供了以下附加事件：

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

Added in version 0.4.

在AutoDoc已读取并处理文档字符串时激发。 lines 是事件处理程序可以修改的字符串列表--已处理的文档字符串的行 in place 来更改Sphinx输入到输出中的内容。

参数:

app -- Sphinx应用程序对象
what -- 文档字符串所属的对象类型（其中之一 'module' , 'class' , 'exception' , 'function' , 'method' , 'attribute' )
name -- 对象的完全限定名称
obj -- 对象本身
options -- 提供给指令的选项：具有属性的对象 inherited_members ， undoc_members ， show_inheritance 和 no-index 如果向AUTO指令提供了相同名称的标志选项，则为真
lines -- 文档字符串的行，请参见上文

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

Added in version 2.4.

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

参数:

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

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

Added in version 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指令提供了相同名称的标志选项，则为真
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[源代码]¶

返回删除第一个 pre 也是最后一次 post 每个文档字符串的行数。如果 what 是一个字符串序列，只有 what 将被处理。

像这样使用(例如，在 setup() 的功能 conf.py )：

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 为True排除，行之间的行与 marker 正则表达式。如果没有匹配的行，则结果文档字符串将为空，因此不会进行任何更改，除非 keepempty 是真的。

如果 what 是一个字符串序列，只有 what 将被处理。

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

在AutoDoc已读取并处理类以确定基类时激发。 bases 是事件处理程序可以修改的类的列表 in place 来更改Sphinx输入到输出中的内容。只有在以下情况下才会发射 show-inheritance 已给出选项。

参数:

app -- Sphinx应用程序对象
name -- 对象的完全限定名称
obj -- 对象本身
options -- 提供给CLASS指令的选项
bases -- 基类签名的列表。请参见上文。

Added in version 4.1.

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

正在跳过成员¶

AutoDoc允许用户使用以下事件定义用于确定是否应将成员包括在文档中的自定义方法：

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

Added in version 0.5.

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

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

参数:

app -- Sphinx应用程序对象
what -- 文档字符串所属的对象类型（其中之一 'module' , 'class' , 'exception' , 'function' , 'method' , 'attribute' )
name -- 对象的完全限定名称
obj -- 对象本身
skip -- 一个布尔值，指示如果用户处理程序不重写决策，自动文档处理程序是否会跳过此成员
options -- 提供给指令的选项：具有属性的对象 inherited_members ， undoc_members ， show_inheritance 和 no-index 如果向AUTO指令提供了相同名称的标志选项，则为真

sphinx.ext.autodoc --包括文档字符串中的文档¶

入门¶

设置¶

确保代码可以导入¶

使用¶

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

文档注释和文档字符串¶

指令¶

默认指令选项¶

自动记录模块¶

自动记录类别或例外¶

自动记录类似功能的对象¶

自动记录属性或数据¶

配置¶

文档字符串预处理¶

正在跳过成员¶

`sphinx.ext.autodoc` --包括文档字符串中的文档¶