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

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

警告

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

如果您记录脚本（而不是库模块），请确保其主例程受 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，但 Sphinx 运行的 Python 环境中没有 foo，则您的模块导入将失败）。

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

使用包含您的包和 Sphinx 的环境。例如，这可以是您的本地开发环境（使用可编辑安装），或者是在 CI 中安装 Sphinx 和您的包的环境。常规的安装过程确保 Sphinx 可以找到您的包，并且所有依赖项都可用。
或者，可以修补 Sphinx 运行，使其可以直接在源代码上运行；例如，如果您希望能够从源代码检出进行 Sphinx 构建。
- 在您的 Sphinx conf.py 中修补 sys.path 以包含您的源代码的文件夹。例如，如果您有一个带有 doc/conf.py 的存储库结构，并且您的包位于 src/mypackage，则应添加
```
sys.path.insert(0, os.path.abspath('../src'))
```
  到您的 conf.py。
- 为了应对缺少的依赖项，请在 autodoc_mock_imports 中指定缺少的模块。

用法¶

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

.. autofunction:: io.open

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

.. automodule:: io
   :members:

指令¶

autodoc 提供了一些指令，它们是通常的 py:module、py:class 等的变体。在解析时，它们会导入相应的模块并提取给定对象的文档字符串，并将它们插入到页面源代码中，位于合适的 py:module、py:class 等指令下。

注意

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

.. automodule::¶

.. autoclass::¶

.. autoexception::¶

文档化模块、类或异常。默认情况下，所有三个指令只会插入对象本身的文档字符串。

.. autoclass:: Noodle

将生成如下源代码

.. class:: Noodle

   Noodle's docstring.

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

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

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

   .. method:: boil(time=10)

      Boil the noodle *time* minutes.

选项

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

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

例如

.. automodule:: noodle
   :members:

将文档化所有模块成员（递归），以及

.. autoclass:: Noodle
   :members:

将文档化所有类成员方法和属性。

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

对于模块，在查找成员时将尊重 __all__，除非您提供 ignore-module-all 标志选项。在没有 ignore-module-all 的情况下，成员的顺序也将是 __all__ 中的顺序。

您还可以提供一个显式的成员列表；然后只会记录这些成员。

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

:undoc-members: (无值)¶

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

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

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

如果设置，autodoc 还将为私有成员生成文档（即，那些命名为 _private 或 __private 的成员）。

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

它还可以将要记录的成员名称的显式列表作为参数。

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

版本 1.1 中新增。

版本 3.2 中更改：此选项现在可以接受参数。

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

如果设置，autodoc 还将为特殊成员生成文档（即，那些命名为 __special__ 的成员）。

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

它还可以将要记录的成员名称的显式列表作为参数。

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

版本 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 中更改：默认选项可以被临时覆盖或扩展。
如果成员的文档字符串在其信息字段列表中包含 :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 中新增。
对于类和异常，在记录所有成员时，将省略从基类继承的成员，除非您除了 members 之外还提供了 inherited-members 选项。
```
.. autoclass:: Noodle
   :members:
   :inherited-members:
```
这可以与 undoc-members 结合使用，以记录类的所有可用成员或模块。

它可以接受一个祖先类，以便不记录从该祖先类继承的成员。默认情况下，不会记录 object 类的成员。要显示所有成员，请向该选项提供 None。

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

另一个示例；如果您的类 Foo 具有 __str__ 特殊方法，并且 autodoc 指令同时具有 inherited-members 和 special-members，则 __str__ 将像过去一样被记录，但其他未在您的类 Foo 中实现的特殊方法。

从 v5.0 开始，它可以接受一个逗号分隔的祖先类列表。它允许通过将选项指定给 automodule 指令，一次性抑制模块上多个类的继承成员。

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

版本 0.3 中新增。

版本 3.0 中更改：它接受祖先类名称作为参数。

版本 5.0 中更改：它接受一个逗号分隔的祖先类名称列表。
可以使用常规语法覆盖显式记录的可调用对象（函数、方法、类）的签名，这将覆盖从内省获得的签名。
```
.. autoclass:: Noodle(type)

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

版本 0.4 中新增。
automodule、autoclass 和 autoexception 指令还支持一个名为 show-inheritance 的标志选项。当给出时，将在类签名下方插入一个基类列表（当与 automodule 一起使用时，这将为模块中记录的每个类插入）。

版本 0.4 中新增。
所有 autodoc 指令都支持 no-index 标志选项，它与标准 py:function 等指令的作用相同：不会为记录的对象（以及所有自动记录的成员）生成索引条目。

版本 0.4 中新增。
automodule 还识别标准 py:module 指令支持的 synopsis、platform 和 deprecated 选项。

版本 0.5 中新增。
automodule 和 autoclass 还具有 member-order 选项，可用于覆盖单个指令的 autodoc_member_order 的全局值。

版本 0.6 中新增。
支持成员文档的指令还具有 exclude-members 选项，如果要记录所有成员，则可以使用该选项排除单个成员名称的文档。

版本 0.6 中新增。
在具有 members 选项设置的 automodule 指令中，只有其 __module__ 属性等于提供给 automodule 的模块名称的模块成员才会被记录。这是为了防止导入的类或函数的文档。如果要阻止此行为并记录所有可用成员，请设置 imported-members 选项。请注意，导入模块的属性不会被记录，因为属性文档是通过解析当前模块的源文件来发现的。

版本 1.2 中新增。
在 autodoc_mock_imports 中添加一个模块列表，以防止导入错误在构建过程中停止，当某些外部依赖项在构建时不可导入时。

版本 1.3 中新增。
作为 autodoc 扩展的提示，您可以在模块名称和对象名称之间放置一个 :: 分隔符，以便在模块名称不明确的情况下让 autodoc 知道正确的模块名称。
```
.. autoclass:: module.name::Noodle
```
autoclass 也识别 class-doc-from 选项，该选项可用于覆盖 autoclass_content 的全局值。

版本 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 选项无效。

对于模块数据成员和类属性，文档可以放在带有特殊格式的注释中（使用 #: 开始注释而不是仅使用 #），或者放在定义后的文档字符串中。注释需要单独成行位于定义之前，或者紧跟在赋值语句之后同一行。后一种形式仅限于一行。

这意味着在以下类定义中，所有属性都可以进行自动文档化。

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 现在可以提取文档字符串。

版本 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": 仅插入类的文档字符串。这是默认值。您仍然可以使用 automethod 或 autoclass 的 members 选项来记录 __init__ 作为单独的方法。
"both": 将类和 __init__ 方法的文档字符串连接起来并插入。
"init": 仅插入 __init__ 方法的文档字符串。

版本 0.3 中新增。

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

版本 1.4 中新增。

autodoc_class_signature¶

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

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

默认值为 "mixed"。

版本 4.1 中新增。

autodoc_member_order¶

此值选择是否按字母顺序（值 'alphabetical'）、按成员类型（值 'groupwise'）或按源代码顺序（值 'bysource'）对自动记录的成员进行排序。默认值为按字母顺序排序。

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

版本 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'。

版本 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'。

版本 1.8 中新增。

版本 2.0 中的更改: 接受 True 作为值。

版本 2.1 中的更改: 添加了 'imported-members'。

版本 4.1 中的更改: 添加了 'class-doc-from'。

版本 4.5 中的更改: 添加了 'no-value'。

autodoc_docstring_signature¶

从 C 模块导入的函数无法进行内省，因此无法自动确定此类函数的签名。但是，一个常用的约定是将签名放在函数文档字符串的第一行。

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

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

版本 1.1 中新增。

3.1 版更改: 支持重载签名

4.0 版更改: 重载签名不需要用反斜杠分隔

autodoc_mock_imports¶

此值包含要模拟的模块列表。当某些外部依赖项在构建时未满足并破坏构建过程时，这很有用。您只能指定依赖项本身的根包并省略子模块。

autodoc_mock_imports = ["django"]

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

版本 1.3 中新增。

1.6 版更改: 此配置值只需要声明应该被模拟的顶层模块。

autodoc_typehints¶

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

'signature' – 在签名中显示类型提示（默认值）
'description' – 将类型提示显示为函数或方法的内容。重载函数或方法的类型提示仍将在签名中表示。
'none' – 不显示类型提示
'both' – 在签名中以及函数或方法的内容中显示类型提示

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

2.1 版新增。

3.0 版新增: 添加了新的选项 'description'。

4.1 版新增: 添加了新的选项 'both'。

autodoc_typehints_description_target¶

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

默认值为 "all"，这意味着所有参数和返回值的类型都已记录，无论它们是否已记录。

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

使用 "documented_params"，仅当参数在文档字符串中记录时才注释参数类型。始终注释返回类型（除非它是 None）。

4.0 版新增。

5.0 版新增: 添加了新的选项 'documented_params'。

autodoc_type_aliases¶

用户定义的类型别名的字典，它将类型名称映射到完全限定的对象名称。它用于保持文档中未评估的类型别名。默认为空 ({})。

只有当您的程序通过 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¶

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

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

4.4 版新增。

5.0 版更改: 默认设置已更改为 'short'

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

4.0 版新增: 作为实验特性添加。这将在将来集成到 autodoc 核心。

autodoc_warningiserror¶: 此值控制导入模块期间 sphinx-build --fail-on-warning 的行为。如果给出 False，则 autodoc 会强制抑制错误，即使导入的模块发出警告。默认情况下为 True。

8.1 版更改: 此选项现在无效，因为 --fail-on-warning 不再提前退出。

autodoc_inherit_docstrings¶

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

默认为 True。

1.7 版新增。

suppress_warnings

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 的对象，如果给定指令相同的名称的标志选项，则这些属性为 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 的对象，如果给定指令相同的名称的标志选项，则这些属性为 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: str | list[str] | None = None) → Callable[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) → Callable[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 的对象，如果给定指令相同的名称的标志选项，则这些属性为 true

上一页

扩展



下一页

sphinx.ext.autosectionlabel – 允许使用标题引用章节

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

入门¶

设置¶

确保代码可导入¶

用法¶

指令¶

配置¶

文档字符串预处理¶

跳过成员¶

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