`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-process-docstring 和 autodoc-process-signature 相同的挂钩预处理文档字符串和签名，就像 autodoc 一样。

选项

如果希望 autosummary 表格也用作 toctree 条目，请使用 toctree 选项，例如
```
.. autosummary::
   :toctree: DIRNAME

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

您还可以使用 caption 选项为 toctree 提供标题。

版本 3.1 中新增: 添加了 caption 选项。

如果您不希望 autosummary 在列表中显示函数签名，请包含 nosignatures 选项

.. autosummary::
   :nosignatures:

   sphinx.environment.BuildEnvironment
   sphinx.util.relative_uri

您可以使用 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¶: 一个字典，用于将值传递到 autosummary 存根文件的模板引擎上下文中。

版本 3.1 中新增。

autosummary_generate¶

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

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

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

版本 2.3 中的变化: 发出 autodoc-skip-member 事件，就像 autodoc 一样。

版本 4.0 中的变化: 默认启用。

autosummary_generate_overwrite¶: 如果为真，则 autosummary 会用生成的存根页面覆盖现有文件。默认为 true（启用）。

版本 3.0 中新增。

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

版本 2.0 中新增。

autosummary_imported_members¶: 一个布尔标志，指示是否记录模块中导入的类和函数。默认为 False

版本 2.1 中新增。

版本 4.4 中的变化: 如果 autosummary_ignore_module_all 为 False，则此配置值将被忽略，适用于 __all__ 中列出的成员。

autosummary_ignore_module_all¶

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

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

版本 4.4 中新增。

autosummary_filename_map¶: 一个将对象名称映射到文件名的字典。这对于避免文件名冲突是必要的，在文件名冲突中，多个对象的名称在不区分大小写的情况下是无法区分的，在文件名不区分大小写的文件系统上。

版本 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 摘要¶