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

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

警告

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

如果您记录脚本（与库模块相对）,请确保其主程序由 if __name__ == '__main__' 条件保护.

为了使这一切正常工作,文档字符串当然必须用正确的 reStructuredText 编写.然后,您可以在文档字符串中使用所有常见的 Sphinx 标记,这些标记最终会正确地出现在文档中.结合手写文档,这种技术减轻了维护两个文档位置的负担,同时避免了自动生成的纯 API 文档的外观.

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

开始

设置

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

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

确保代码可以被导入

autodoc 在导入模块后通过反射分析代码和文档字符串.为了使导入正常工作,您必须确保 Sphinx 可以找到您的模块,并且可以解析依赖关系（如果您的模块执行 import foo ,但在 Sphinx 运行的 Python 环境中 foo 不可用,那么您的模块导入将失败）.

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

  1. 使用一个包含您的包和 Sphinx 的环境.这可以是您的本地开发环境（使用可编辑安装）,或在 CI 中安装 Sphinx 和您的包的环境.常规安装过程确保 Sphinx 能找到您的包,并且所有依赖项都可用.

  2. 可以选择修补 Sphinx 运行,以便它可以直接在源代码上操作;例如,如果你想能够从源代码检出进行 Sphinx 构建.

    • 在你的 Sphinx :file :conf.py 中修改 sys.path 以包含你的源文件夹.例如,如果你的仓库结构为 doc/conf.py ,而你的包位于 src/mypackage ,那么你应该添加:

      sys.path.insert(0, os.path.abspath('../src'))

      到你的 conf.py .

    • 为了应对缺失的依赖项,请在 autodoc_mock_imports 中指定缺失的模块.

使用

现在你可以使用 :ref :autodoc-directives 为 Python 代码元素,如函数、类、模块等,添加格式化的文档.例如,要记录函数 io.open() ,可以从源文件中读取其签名和文档字符串,你可以这样写

.. autofunction:: io.open

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

.. automodule:: io
   :members:

指令

autodoc 提供了几种指令版本,类似于常用的 py:module 、py:class 等.在解析时,它们导入相应的模块并提取给定对象的文档字符串,将其插入到适当的 py:module 、py:class 等指令下的页面源中.

备注

就像 py:class 尊重当前的 py:module , autoclass 也会做到这一点.同样,:rst:dir:automethod 将尊重当前的 py:class .

.. automodule::
.. autoclass::
.. autoexception::

文档一个模块、类或异常.默认情况下,所有三个指令仅插入对象本身的文档字符串:

.. autoclass:: Noodle

将生成如下源代码:

.. class:: Noodle

   Noodle's 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 .

    小技巧

    您可以使用否定形式 :samp:’no-{flag}’ 作为 autodoc 指令的选项,临时禁用它.例如:

    .. automodule:: foo
   :no-undoc-members:

    小技巧

    您可以使用autodoc指令选项暂时覆盖或扩展默认选项,这些选项接受列表作为输入.例如:

    .. autoclass:: Noodle
   :members: eat
   :private-members: +_spicy, _garlickly

    在 3.5 版本发生变更: 默认选项可以被暂时覆盖或扩展.

  • autodoc 如果其文档字符串包含 :meta private: 在其 信息字段列表 中,则将成员视为私有.例如:

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

    :meta private:
    """

    Added in version 3.0.

  • autodoc 将成员视为公共,如果其文档字符串在其 信息字段列表 中包含 :meta public: ,即使它以下划线开头.例如:

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

    :meta public:
    """

    Added in version 3.1.

  • autodoc认为,如果变量成员的文档字符串中包含 :meta hide-value: ,则该变量没有任何默认值,具体见其:ref:info-field-lists .示例:

    var1 = None  #: :meta hide-value:

    Added in version 3.5.

  • 对于类和异常,除非您在 members 外还提供 inherited-members 选项,否则文档中将省略从基类继承的成员:

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

    这可以与 undoc-members 结合使用,以文档记录类或模块的 所有 可用成员.

    可以使用祖先类来控制不记录从中继承的成员.默认情况下, object 类的成员不会被记录.要显示它们全部,请将选项设置为 None .

    例如;如果你的类 Foo 是从 list 类派生的,并且你不想文档化 list.__len__() ,你应该指定选项 :inherited-members: list 以避免列表类的特殊成员.

    另一个例子;如果你的类 Foo 有 __str__ 特殊方法,并且 autodoc 指令同时包括 inherited-members 和 special-members ,那么 __str__ 会像过去一样被文档化,但其他在你的类 Foo 中未实现的特殊方法将不会被文档化.

    自 v5.0 起,可以接受一个以逗号分隔的祖先类列表.通过指定选项给 automodule 指令,可以同时抑制模块中多个类的继承成员.

    注意:如果继承的成员来自于没有按照reStructuredText格式编写文档字符串的模块,将导致标记错误.

    Added in version 0.3.

    在 3.0 版本发生变更: 它将一个祖先类名作为参数.

    在 5.0 版本发生变更: 它接受一个以逗号分隔的祖先类名称列表.

  • 可以使用常规语法覆盖显式文档中可调用对象（函数、方法、类）的签名,这将覆盖通过 introspection 获得的签名:

    .. autoclass:: Noodle(type)

   .. automethod:: eat(persona)

    这在方法的签名被装饰器隐藏时很有用.

    Added in version 0.4.

  • The automodule, autoclass and autoexception directives also support a flag option called show-inheritance. When given, a list of base classes will be inserted just below the class signature (when used with automodule, this will be inserted for every class that is documented in the module).

    Added in version 0.4.

  • 所有的自动文档指令都支持 no-index 标志选项,其效果与标准 py:function 等指令相同:不为被文档化的对象（及所有自动文档成员）生成索引条目.

    Added in version 0.4.

  • automodule 还识别标准 py:module 指令所支持的 synopsis 、 platform 和 deprecated 选项.

    Added in version 0.5.

  • automodule 和 autoclass 也有一个 member-order 选项,可以用来覆盖一个指令的全局值 autodoc_member_order .

    Added in version 0.6.

  • 支持成员文档的指令也有一个 exclude-members 选项,可以用于从文档中排除单个成员名,如果所有成员都要被文档化.

    Added in version 0.6.

  • 在带有 members 选项设置的 automodule 指令中,只有那些 __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 等相同,但不提供用于自动成员文档的选项.

:rst :dir:`autodata` 和 autoattribute 支持 annotation 选项.该选项控制变量值的显示方式.如果不带参数指定,则只会打印变量的名称,而不显示其值:

.. autodata:: CD_DRIVE
   :annotation:

如果选项指定了参数,它将在名称后作为变量的值打印:

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

默认情况下,如果没有 annotation 选项,Sphinx会尝试获取变量的值并在其名称后打印.

The no-value option can be used instead of a blank annotation to show the type hint but not the value:

.. 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 或 members 选项来单独记录 __init__ 方法.

"both"

此类和 __init__ 方法的文档字符串被连接并插入.

"init"

只插入了 __init__ 方法的文档字符串.

Added in version 0.3.

如果类没有 __init__ 方法,或者 __init__ 方法的文档字符串为空,但类有 __new__ 方法的文档字符串,则使用 __new__ 方法的文档字符串.

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

这个值是一个自动文档指令标志的列表,这些标志应自动应用于所有自动文档指令.支持的标志有 '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_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模块导入的函数无法被反射,因此无法自动确定这些函数的签名.然而,通常的约定是在函数的文档字符串的第一行中放置签名.

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

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

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

类型别名仅在您的程序通过 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:

   ...

Added in version 3.3.

autodoc_typehints_format

该值控制类型提示的格式.设置可以取以下值:

  • ‘fully-qualified’``– 显示模块名称及其类型提示的名称

  • ‘short’ -- 抑制类型提示的前导模块名称 (例如 io.StringIO -> StringIO``) (默认)

Added in version 4.4.

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

autodoc_preserve_defaults

如果为 True,函数的默认参数值将在生成文档时不被评估.它将其按原样保留在源代码中.

Added in version 4.0: 作为一个实验性功能添加.将来会将其集成到autodoc核心中.

autodoc_warningiserror

此值控制在导入模块时 sphinx-build --fail-on-warning 的行为.如果给定 False ,则 autodoc 强制抑制错误,即使导入的模块发出警告.默认值为 True .

在 8.1 版本发生变更: 此选项现在无效,因为 --fail-on-warning 不再提前退出.

autodoc_inherit_docstrings

这个值控制文档字符串的继承.如果设置为 True,则类或方法的文档字符串（如果没有明确设置）将继承自父类.

默认值是 True .

Added in version 1.7.

suppress_warnings

autodoc 支持通过 suppress_warnings 来抑制警告信息.它还允许以下警告类型:

  • autodoc

  • autodoc.import_object

文档字符串预处理

autodoc 提供了以下额外事件:

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

Added in version 0.4.

当autodoc读取并处理了文档字符串时发出.*lines*是一个字符串列表——处理后的文档字符串的行——事件处理程序可以**就地**修改这些行,以更改Sphinx在输出中放入的内容.

参数:

  • app – Sphinx 应用对象

  • what – 文档字符串所属对象的类型（之一为 "module" 、 "class" 、 "exception" 、 "function" 、 "method" 、 "attribute" ）

  • name – 对象的完全限定名称

  • obj – the object itself

  • options – 给指令的选项:一个对象,具有属性 inherited_members , undoc_members , show_inheritance 和 no-index ,如果给予相同名称的自动指令的标志选项为真

  • lines – 文档字符串的行,如上所示

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

Added in version 2.4.

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

参数:

  • app – Sphinx 应用对象

  • obj – the object itself

  • 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 – the object itself

  • options – 给指令的选项:一个对象,具有属性 inherited_members , undoc_members , show_inheritance 和 no-index ,如果给予相同名称的自动指令的标志选项为真

  • signature – 函数签名,格式为字符串”(parameter_1, parameter_2)”,如果反射未成功并且指令中未指定签名,则为”None”.

  • return_annotation – 函数返回注释,格式为 " -> 注释" ,如果没有返回注释则返回 None

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

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

返回一个监听器,该监听器移除每个文档字符串的第一个 pre 和最后一个 post 行.如果 what 是一个字符串序列,只有 what 中类型的文档字符串会被处理.

像这样使用（例如在:file: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[源代码]

返回一个监听器,该监听器在匹配*marker*正则表达式的行之间保留或（如果*exclude*为真）排除行.如果没有行匹配,结果文档字符串将为空,因此,除非*keepempty*为真,否则不会做出更改.

如果 what 是一个字符串序列,则只有 what 中某种类型的文档字符串会被处理.

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

当autodoc读取并处理了一个类以确定基类时,会发出此事件.*bases*是一个类的列表,事件处理程序可以**就地**修改它,以更改Sphinx放入输出中的内容.仅在给定 show-inheritance 选项时发出此事件.

参数:

  • app – Sphinx 应用对象

  • name – 对象的完全限定名称

  • obj – the object itself

  • options – 类指令给出的选项

  • bases – 基础类签名的列表.见上文.

Added in version 4.1.

在 4.3 版本发生变更: bases can contain a string as a base class name. It will be processed as reStructuredText.

跳过成员

autodoc 允许用户通过以下事件定义自定义方法,以确定某个成员是否应该包含在文档中:

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

Added in version 0.5.

当自动文档生成器需要决定某个成员是否应包括在文档中时会发出此信号.如果处理程序返回 True ,则该成员将被排除.如果处理程序返回 False ,则该成员将被包含.

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

参数:

  • app – Sphinx 应用对象

  • what – 文档字符串所属对象的类型（之一为 "module" 、 "class" 、 "exception" 、 "function" 、 "method" 、 "attribute" ）

  • name – 对象的完全限定名称

  • obj – the object itself

  • skip – 一个布尔值,指示如果用户处理程序未覆盖决策,autodoc 是否将跳过此成员

  • options – 给指令的选项:一个对象,具有属性 inherited_members , undoc_members , show_inheritance 和 no-index ,如果给予相同名称的自动指令的标志选项为真