`sphinx.ext.autosummary` – 生成 autodoc 摘要¶

在 0.6 版本中添加。

此扩展生成函数/方法/属性摘要列表，类似于 Epydoc 和其他 API 文档生成工具输出的列表。当您的文档字符串很长且详细时，将每个文档字符串放在单独的页面上可以使其更易于阅读，这尤其有用。

sphinx.ext.autosummary 扩展通过两个部分完成此操作

有一个 autosummary 指令，用于生成摘要列表，其中包含指向文档项的链接，以及从其文档字符串中提取的简短摘要。
autosummary 指令还会为其内容中列出的条目生成简短的“存根”文件。默认情况下，这些文件仅包含相应的 sphinx.ext.autodoc 指令，但可以使用模板进行自定义。

sphinx-autogen 脚本也能够从命令行生成“存根”文件。

.. autosummary::¶

插入一个表格，其中包含指向文档项的链接，以及每个文档项的简短摘要（文档字符串的第一句话）。

autosummary 指令还可以选择充当包含项的 toctree 条目。可选地，当 autosummary_generate 为 True 时，也可以自动生成这些项的存根 .rst 文件。

例如，

.. currentmodule:: sphinx

.. autosummary::

   environment.BuildEnvironment
   util.relative_uri

生成如下表格

`environment.BuildEnvironment`(app)	ReST 文件在其中转换的环境。
`util.relative_uri`(base, to)	返回从 `base` 到 `to` 的相对 URL。

Autosummary 使用与 autodoc 相同的 autodoc-process-docstring 和 autodoc-process-signature 钩子预处理文档字符串和签名。

选项

:class: class names （类名列表，以空格分隔）¶: 将 class 属性分配给表格。这是一个常用选项。

在 8.2 版本中添加。

:toctree: 可选的目录名称¶

如果您希望 autosummary 表格也充当 toctree 条目，请使用 toctree 选项，例如

.. autosummary::
   :toctree: DIRNAME

   sphinx.environment.BuildEnvironment
   sphinx.util.relative_uri

toctree 选项还向 sphinx-autogen 脚本发出信号，表明应为此指令中列出的条目生成存根页面。该选项接受目录名称作为参数；默认情况下，sphinx-autogen 将其输出放置在此目录中。如果未给出参数，则输出将放置在包含指令的文件所在的目录中。

在 0.6 版本中添加。

:caption: ToC 的标题¶: 向 toctree 添加标题。

在 3.1 版本中添加。

:signatures: 格式¶

如何显示签名。有效值为

long (默认): 使用长签名。这仍然会被截断，以便名称加上签名不超过一定长度。
short: 函数和类签名显示为 (…) （如果它们有参数），显示为 () （如果它们没有参数）。
none: 不显示签名。

在 8.2 版本中添加。

:nosignatures:¶

不在摘要中显示函数签名。

这等效于 :signatures: none。

在 0.6 版本中添加。

在 8.2 版本中更改: 此指令选项已被更通用的 :signatures: none 取代。

它将在 Sphinx 的未来版本中弃用并删除。

:template: 文件名¶

指定用于渲染摘要的自定义模板。例如，

.. autosummary::
   :template: mytemplate.rst

   sphinx.environment.BuildEnvironment

将使用您的 templates_path 中的模板 mytemplate.rst 来生成列出的所有条目的页面。请参阅下面的自定义模板。

在 1.0 版本中添加。

:recursive:¶

递归地为模块和子包生成文档。例如，

.. autosummary::
   :recursive:

   sphinx.environment.BuildEnvironment

在 3.1 版本中添加。

sphinx-autogen – 生成 autodoc 存根页面¶

sphinx-autogen 脚本可用于方便地为 autosummary 列表中包含的项目生成存根文档页面。

例如，命令

$ sphinx-autogen -o generated *.rst

将读取具有 :toctree: 选项集的所有 *.rst 文件中的所有 autosummary 表格，并为所有文档项目在目录 generated 中输出相应的存根页面。默认情况下，生成的页面包含以下形式的文本

sphinx.util.relative_uri
========================

.. autofunction:: sphinx.util.relative_uri

如果未给出 -o 选项，则脚本会将输出文件放置在 :toctree: 选项中指定的目录中。

有关更多信息，请参阅 sphinx-autogen 文档

自动生成存根页面¶

如果您不想使用 sphinx-autogen 创建存根页面，您也可以使用这些配置值

autosummary_context¶

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

要传递到 autosummary 存根文件的模板引擎上下文中的值字典。

在 3.1 版本中添加。

autosummary_generate¶

类型:: bool
默认:: True

布尔值，指示是否扫描所有找到的文档以查找 autosummary 指令，并为每个指令生成存根页面。

也可以是要为其生成存根页面的文档列表。

新文件将放置在指令的 :toctree: 选项中指定的目录中。

在 2.3 版本中更改: 发出 autodoc-skip-member 事件，与 autodoc 的行为相同。

在 4.0 版本中更改: 默认启用。

autosummary_generate_overwrite¶

类型:: bool
默认:: True

如果为 true，则 autosummary 将覆盖已生成的存根页面的现有文件。

在 3.0 版本中添加。

autosummary_mock_imports¶

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

此值包含要模拟的模块列表。有关更多详细信息，请参阅 autodoc_mock_imports。它默认为 autodoc_mock_imports。

在 2.0 版本中添加。

autosummary_imported_members¶

类型:: bool
默认:: False

一个布尔标志，指示是否记录模块中导入的类和函数。

在 2.1 版本中添加。

在 4.4 版本中更改: 如果 autosummary_ignore_module_all 为 False，则对于 __all__ 中列出的成员，将忽略此配置值。

autosummary_ignore_module_all¶

类型:: bool
默认:: True

如果 False 且模块设置了 __all__ 属性，则 autosummary 会记录 __all__ 中列出的每个成员，而不会记录其他成员。

请注意，如果导入的成员在 __all__ 中列出，则无论 autosummary_imported_members 的值如何，都会对其进行记录。要匹配 from module import * 的行为，请将 autosummary_ignore_module_all 设置为 False，并将 autosummary_imported_members 设置为 True。

在 4.4 版本中添加。

autosummary_filename_map¶

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

将对象名称映射到文件名的字典。这对于避免文件名冲突是必要的，在文件名不区分大小写的文件系统上，多个对象具有在忽略大小写时无法区分的名称。

在 3.2 版本中添加。

自定义模板¶

在 1.0 版本中添加。

您可以自定义存根页面模板，方式与 HTML Jinja 模板类似，请参阅模板。 (TemplateBridge 不受支持。)

注意

如果您发现自己花费大量时间调整存根模板，这可能表明最好编写自定义叙述性文档。

Autosummary 使用以下 Jinja 模板文件

autosummary/base.rst – 备用模板
autosummary/module.rst – 模块的模板
autosummary/class.rst – 类的模板
autosummary/function.rst – 函数的模板
autosummary/attribute.rst – 类属性的模板
autosummary/method.rst – 类方法的模板

以下变量在模板中可用

name¶: 文档对象的名称，不包括模块和类部分。

objname¶: 文档对象的名称，不包括模块部分。

fullname¶: 文档对象的完整名称，包括模块和类部分。

objtype¶: 文档对象的类型，可以是 "module"、"function"、"class"、"method"、"attribute"、"data"、"object"、"exception"、"newvarattribute"、"newtypedata"、"property" 之一。

module¶: 文档对象所属模块的名称。

class¶: 文档对象所属类的名称。仅适用于方法和属性。

underline¶: 包含 len(full_name) * '=' 的字符串。请改用 underline 过滤器。

members¶: 包含模块或类的所有成员名称的列表。仅适用于模块和类。

inherited_members¶: 包含类的所有继承成员名称的列表。仅适用于类。

在 1.8.0 版本中添加。

functions¶: 包含模块中“公共”函数名称的列表。此处，“公共”表示名称不以下划线开头。仅适用于模块。

classes¶: 包含模块中“公共”类名称的列表。仅适用于模块。

exceptions¶: 包含模块中“公共”异常名称的列表。仅适用于模块。

methods¶: 包含类中“公共”方法名称的列表。仅适用于类。

attributes¶: 包含类/模块中“公共”属性名称的列表。仅适用于类和模块。

在 3.1 版本中更改: 支持模块的属性。

modules¶: 包含包中“公共”模块名称的列表。仅适用于作为包且 recursive 选项处于打开状态的模块。

在 3.1 版本中添加。

此外，以下过滤器可用

escape(s)¶: 转义文本中的任何特殊字符，以便在格式化 RST 上下文中使用。例如，这可以防止星号使内容加粗。这取代了内置的 Jinja escape 过滤器，后者执行 html 转义。

underline(s, line='='): 向一段文本添加标题下划线。

例如，{{ fullname | escape | underline }} 应用于生成页面的标题。

注意

您可以在存根页面中使用 autosummary 指令。存根页面也是基于这些指令生成的。

sphinx.ext.autosummary – 生成 autodoc 摘要¶

sphinx-autogen – 生成 autodoc 存根页面¶

自动生成存根页面¶

自定义模板¶

`sphinx.ext.autosummary` – 生成 autodoc 摘要¶