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

这个扩展可以导入您正在记录的模块，并以半自动的方式从docstring中拉入文档。

备注

为了让sphinx（实际上是执行sphinx的python解释器）找到您的模块，它必须是可导入的。这意味着模块或包必须位于 sys.path --适应你的生活 sys.path 在相应的配置文件中。

警告

autodoc 进口要记录的模块。如果任何模块在导入时有副作用，这些将由 autodoc 什么时候？ sphinx-build 运行。

如果您记录脚本（与库模块不同），请确保它们的主例程受 if __name__ == '__main__' 条件。

为了使其工作，文档字符串当然必须用正确的RestructedText编写。然后，您可以在docstrings中使用所有常见的sphinx标记，它将在文档中正确结束。与手工编写的文档一起，这种技术减轻了为文档维护两个位置的痛苦，同时避免了自动生成的纯API文档。

如果你喜欢 NumPy 或 Google 在RestructuredText上设置DocStrings样式，还可以启用 napoleon 延伸。 napoleon 是一个预处理器，用于将docstring转换为之前正确的restructuredtext autodoc 处理它们。

指令¶

autodoc 提供多个指令，这些指令是常规的版本 py:module ， py:class 诸如此类。在解析时，它们导入相应的模块并提取给定对象的docstring，将它们插入到合适的 py:module ， py:class 等指令。

备注

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

.. automodule::¶

.. autoclass::¶

.. autoexception::¶

记录模块、类或异常。默认情况下，这三个指令都只插入对象本身的docstring:：

.. autoclass:: Noodle

将生成这样的源：

.. class:: Noodle

   Noodle's docstring.

“auto”指令也可以包含自己的内容，它将插入到docstring之后（但在任何自动成员文档之前）生成的非auto指令源中。

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

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

   .. method:: boil(time=10)

      Boil the noodle *time* minutes.

选项

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

如果设置，AutoDoc将为目标模块、类或异常的成员生成文档。

例如：：

.. automodule:: noodle
   :members:

将记录所有模块成员（递归），并且：

.. autoclass:: Noodle
   :members:

将记录所有类成员方法和属性。

默认情况下，AutoDoc不会为私有成员、没有文档字符串、从超类继承的成员或特殊成员生成文档。

对于模块， __all__ 在寻找成员时会受到尊重，除非 ignore-module-all 标志选项。没有 ignore-module-all ，成员的顺序也将是 __all__ .

您还可以给出一个明确的成员列表；只有这些成员才会被记录：

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

:undoc-members: (no value)¶

如果设置，AutoDoc还将为没有文档字符串的成员生成文档：：

.. automodule:: noodle
   :members:
   :undoc-members:

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

如果设置，AutoDoc还将为私有成员(即，名为 _private 或 __private )：

.. automodule:: noodle
   :members:
   :private-members:

它还可以采用一个显式的成员名称列表作为参数进行记录：

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

Added in version 1.1.

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

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

如果设置，AUTODOC还将为特殊成员(即，名为 __special__ )：

.. autoclass:: my.Class
   :members:
   :special-members:

它还可以采用一个显式的成员名称列表作为参数进行记录：

.. autoclass:: my.Class
   :members:
   :special-members: __init__, __name__

Added in version 1.1.

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

选项和高级用法

如果你想 members 选项（或下面描述的其他选项）默认值，请参见 autodoc_default_options .
小技巧

你可以用否定的形式， 'no-{flag}' 作为autoDoc指令的一个选项，暂时禁用它。例如：：
```
.. automodule:: foo
   :no-undoc-members:
```
小技巧

您可以使用AUTODOC指令选项临时覆盖或扩展默认选项，默认选项将列表作为输入。例如：：
```
.. autoclass:: Noodle
   :members: eat
   :private-members: +_spicy, _garlickly
```
在 3.5 版本发生变更: 可以临时覆盖或扩展默认选项。

如果autodoc的docstring包含 :meta private: 在其信息字段列表 . 例如：

def my_function(my_arg, my_other_arg):
    """blah blah blah

    :meta private:
    """

Added in version 3.0.

如果autodoc的docstring包含 :meta public: 在其信息字段列表，即使它以下划线开头。例如：
```
def _my_function(my_arg, my_other_arg):
    """blah blah blah

    :meta public:
    """
```
Added in version 3.1.
如果变量成员的文档字符串包含 :meta hide-value: 在ITS中信息字段列表。示例：
```
var1 = None  #: :meta hide-value:
```
Added in version 3.5.
对于类和异常，在记录所有成员时，从基类继承的成员将被忽略，除非 inherited-members 选项，除了 members ：：
```
.. autoclass:: Noodle
   :members:
   :inherited-members:
```
这可以与 undoc-members 公文 all 类或模块的可用成员。

它可以使用一个祖先类来不记录继承自它的成员。默认情况下，成员 object 类没有记录。给他们看，给 None 选择。

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

另一个例子；如果你的类Foo有 __str__ 特殊方法和autodoc指令都有 inherited-members 和 special-members ， __str__ 将像以前一样被记录，但是在类中没有实现的其他特殊方法 Foo .

从V5.0开始，它可以接受祖先类的逗号分隔列表。通过将选项指定为，它允许同时取消模块上多个类的继承成员 automodule 指令。

注意：如果继承的成员来自文档字符串不是REST格式的模块，这将导致标记错误。

Added in version 0.3.

在 3.0 版本发生变更: 它以祖先类名作为参数。

在 5.0 版本发生变更: 它使用逗号分隔的祖先类名称列表。
可以使用常规语法重写显式记录的可调用对象（函数、方法、类）的签名，该语法将重写自省获得的签名：
```
.. autoclass:: Noodle(type)

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

Added in version 0.4.
这个 automodule ， autoclass 和 autoexception 指令还支持名为 show-inheritance . 给定后，将在类签名的正下方插入一个基类列表（与一起使用时 automodule ，这将为模块中记录的每个类插入）。

Added in version 0.4.
所有的AutoDoc指令都支持 no-index 与标准具有相同效果的标志选项 py:function 等指令：不会为记录的对象(以及所有自动记录的成员)生成索引项。

Added in version 0.4.
automodule 也承认 synopsis ， platform 和 deprecated 选择标准 py:module 指令支持。

Added in version 0.5.
automodule 和 autoclass 也有一个 member-order 可用于重写的全局值的选项 autodoc_member_order 对于一个指令。

Added in version 0.6.
支持成员文档的指令还具有 exclude-members 如果要记录所有成员，则可用于从文档中排除单个成员名称的选项。

Added in version 0.6.
在一个 automodule 指令 members 选项集，仅模块成员 __module__ 属性等于给定的模块名称 automodule 将被记录。这是为了防止导入类或函数的文档化。设置 imported-members 如果要阻止此行为并记录所有可用成员，则选择此选项。请注意，不会记录来自导入模块的属性，因为通过分析当前模块的源文件可以发现属性文档。

Added in version 1.2.
在中添加模块列表 autodoc_mock_imports 防止导入错误，以便在生成时某些外部依赖项不可导入时停止生成过程。

Added in version 1.3.
作为对autodoc扩展的提示，可以将 :: 在模块名和对象名之间使用分隔符，以便autodoc在模块名不明确时知道正确的模块名。:
```
.. autoclass:: module.name::Noodle
```
autoclass 还认识到 class-doc-from 选项，该选项可用于重写 autoclass_content 。

Added in version 4.1.

.. autofunction::¶

.. autodecorator::¶

.. autodata::¶

.. automethod::¶

.. autoattribute::¶

.. autoproperty::¶

这些工作原理和 autoclass 等，但不提供用于自动成员文档的选项。

autodata 和 autoattribute 支持 annotation 选项。该选项控制变量值的显示方式。如果不带参数指定，则只打印变量的名称，而不显示其值：：

.. autodata:: CD_DRIVE
   :annotation:

如果使用参数指定选项，则在变量名后面打印该选项：

.. autodata:: CD_DRIVE
   :annotation: = your CD device name

默认情况下，没有 annotation 选项，sphinx尝试获取变量的值，并将其打印在名称之后。

这个 no-value 选项可以用来代替空白 annotation 要显示类型提示而不显示值，请执行以下操作：：

.. autodata:: CD_DRIVE
   :no-value:

如果两个 annotation 和 no-value 使用选项， no-value 没有任何效果。

对于模块数据成员和类属性，可以将文档放入具有特殊格式的注释中（使用 #: 开始评论而不是仅仅 # ）或在docstring中之后定义。注释必须在自己的行上之前定义，或在分配之后 在同一条线上 . 后一种形式仅限于一行。

这意味着在以下类定义中，可以自动记录所有属性：

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

在 0.6 版本发生变更: autodata 和 autoattribute 现在可以提取docstrings。

在 1.1 版本发生变更: 分配后，现在允许在同一行上使用注释文档。

在 1.2 版本发生变更: autodata 和 autoattribute 有一个 annotation 选择权。

在 2.0 版本发生变更: autodecorator 补充。

在 2.1 版本发生变更: autoproperty 添加了。

在 3.4 版本发生变更: autodata 和 autoattribute 现在有一个 no-value 选项。

备注

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

配置¶

还可以设置配置值：

autoclass_content¶

此值选择要插入到 autoclass 指令。可能的值为：

"class": 只插入类的docstring。这是默认设置。您仍然可以记录 __init__ 作为一种单独的方法 automethod 或 members 选择权 autoclass .
"both": 两个班级和 __init__ 方法的docString被连接并插入。
"init": __init__ 方法的docString已插入。

Added in version 0.3.

如果全班没有 __init__ 方法或如果 __init__ 方法的docString为空，但类具有 __new__ 方法的docString，它被使用。

Added in version 1.4.

autodoc_class_signature¶

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

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

缺省值为 "mixed" 。

Added in version 4.1.

autodoc_member_order¶

此值选择自动记录的成员是否按字母顺序排序（值 'alphabetical' ，按成员类型（值） 'groupwise' ）或按来源顺序（值 'bysource' ）默认值按字母顺序排列。

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

Added in version 0.6.

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

autodoc_default_flags¶: 此值是应自动应用于所有AutoDoc指令的AutoDoc指令标志列表。支持的标志是 'members' ， 'undoc-members' ， 'private-members' ， 'special-members' ， 'inherited-members' ， 'show-inheritance' ， 'ignore-module-all' 和 'exclude-members' .

Added in version 1.0.

自 1.8 版本弃用: 融入 autodoc_default_options .

autodoc_default_options¶

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

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

设置 None 或 True 值等于只给指令指定选项名。

支持的选项包括 'members' ， 'member-order' ， 'undoc-members' ， 'private-members' ， 'special-members' ， 'inherited-members' ， 'show-inheritance' ， 'ignore-module-all' ， 'imported-members' ， 'exclude-members' ， 'class-doc-from' 和 'no-value' 。

Added in version 1.8.

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

在 2.1 版本发生变更: 补充 'imported-members' .

在 4.1 版本发生变更: 增列 'class-doc-from' 。

在 4.5 版本发生变更: 增列 'no-value' 。

autodoc_docstring_signature¶

从C模块导入的函数不能进行内省，因此无法自动确定这些函数的签名。然而，将签名放入函数docstring的第一行是一种常用的约定。

如果此布尔值设置为 True （默认情况下），autodoc将查看docstring的第一行中的函数和方法，如果它看起来像签名，则使用该行作为签名，并将其从docstring内容中删除。

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

Added in version 1.1.

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

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

autodoc_mock_imports¶

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

autodoc_mock_imports = ["django"]

将模仿所有进口商品 django 包裹。

Added in version 1.3.

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

autodoc_typehints¶

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

'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¶

此值控制是否记录未记录的参数和返回值的类型 autodoc_typehints 设为 description 。

缺省值为 "all" 意味着所有参数和返回值的类型都有文档记录，无论它们是否有文档记录。

当设置为时 "documented" ，则只会记录已由文档字符串记录的参数或返回值的类型。

使用 "documented_params" ，只有在文档字符串中记录了参数时，才会对参数类型进行注释。返回类型始终是带注释的(除非带注释 None )。

Added in version 4.0.

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

autodoc_type_aliases¶

为用户定义的词典 `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¶

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

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

Added in version 4.4.

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

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

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

autodoc_warningiserror¶: 此值控制 sphinx-build -W 在导入模块时。如果 False 如果输入的模块发出警告，AutoDoc将强制抑制错误。默认情况下， True .

autodoc_inherit_docstrings¶

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

默认值为 True .

Added in version 1.7.

suppress_warnings

autodoc 支持通过以下方式抑制警告消息 suppress_warnings 。此外，它还允许以下警告类型：

自动对接
autodoc.import_object

文档字符串预处理¶

AutoDoc提供以下附加事件：

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

Added in version 0.4.

当AutoDoc已读取并处理docString时发出。线是事件处理程序可以修改的字符串列表（已处理docstring的行）就位改变Sphinx的输出。

参数:

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

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 -- docstring所属对象的类型（其中一个 "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 模块为事件中通常需要的docstring处理提供工厂功能 autodoc-process-docstring ：

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

返回删除第一个 pre 最后 post 每个docstring的行。如果 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) → Callable[源代码]¶

返回保留的侦听器，或者如果排除是真的，不包括，行之间的行与标记正则表达式。如果没有匹配的行，则生成的docstring将为空，因此不会进行任何更改，除非 保持空 是真的。

如果 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 可以包含一个字符串作为基类名称。它将被作为REST标记的文本处理。

正在跳过成员¶

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

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

Added in version 0.5.

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

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

参数:

app -- sphinx应用程序对象
what -- docstring所属对象的类型（其中一个 "module" ， "class" ， "exception" ， "function" ， "method" ， "attribute" ）
name -- 对象的完全限定名
obj -- 对象本身
skip -- 一个布尔值，指示如果用户处理程序不重写该决定，autoDoc是否将跳过此成员。
options -- 提供给指令的选项：具有属性的对象 inherited_members ， undoc_members ， show_inheritance 和 no-index 如果向AUTO指令提供了相同名称的标志选项，则为真

Sphinx

On this page

Site navigation

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

指令¶

配置¶

文档字符串预处理¶

正在跳过成员¶

Sphinx

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

指令¶

配置¶

文档字符串预处理¶

正在跳过成员¶

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