`sphinx.ext.autosummary` --生成自动文档摘要¶

Added in version 0.6.

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

这个 sphinx.ext.autosummary 扩展通过两个部分来完成这项工作：

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

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

.. autosummary::¶

插入一个包含指向已记录项目的链接的表格，并为每个项目插入简短的摘要简介(文档字符串的第一句话)。

这个 autosummary 指令还可以选择性地充当 toctree 包含项的条目。可选的存根 .rst 在以下情况下，也可以自动生成这些项目的文件 autosummary_generate 是 True 。

例如：：

.. currentmodule:: sphinx

.. autosummary::

   environment.BuildEnvironment
   util.relative_uri

生成如下所示的表：

`environment.BuildEnvironment` \(应用)	在其中转换REST文件的环境。
`util.relative_uri`(base, to)	从返回相对URL `base` 至 `to` 。

自动汇总对文档字符串和签名使用相同的 autodoc-process-docstring 和 autodoc-process-signature 挂钩为 autodoc 。

选项

:class: class names (a list of class names, separated by spaces)¶: 分配 class attributes 到桌子上。这是一 common option .

Added in version 8.2.

:toctree: optional directory name¶

如果您想要 autosummary 表也可用作 toctree 条目，请使用 toctree 选项，例如：：

.. autosummary::
   :toctree: DIRNAME

   sphinx.environment.BuildEnvironment
   sphinx.util.relative_uri

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

Added in version 0.6.

:caption: caption of ToC¶: 在toctree中添加标题。

Added in version 3.1.

:signatures: format¶

如何显示签名。有效值为

long ( default ）：使用长签名。这仍然被切断，以便姓名和签名不会被保留一定的长度。
short ：函数和类签名显示为 (…) 如果他们有争论并且 () 如果他们没有争论的话。
none ：不显示签名。

Added in version 8.2.

:nosignatures:¶

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

这相当于 :signatures: none .

Added in version 0.6.

在 8.2 版本发生变更: 指令选项已被更通用的选项取代 :signatures: none .

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

:template: filename¶

指定用于呈现摘要的自定义模板。例如：

.. autosummary::
   :template: mytemplate.rst

   sphinx.environment.BuildEnvironment

将使用模板 mytemplate.rst 在你的 templates_path 为列出的所有条目生成页面。看见 Customizing templates 下面。

Added in version 1.0.

:recursive:¶

以迭代方式生成模块和子包的文档。例如：

.. autosummary::
   :recursive:

   sphinx.environment.BuildEnvironment

Added in version 3.1.

sphinx-autogen --生成自动文档存根页面¶

这个 sphinx-autogen 脚本可用于方便地为中包含的项目生成存根文档页面 autosummary 挂牌信息。

例如，命令：：

$ sphinx-autogen -o generated *.rst

将阅读所有内容 autosummary 表中的表 *.rst 具有 :toctree: 选项集，并在目录中输出相应的存根页面 generated 对于所有记录的项目。默认情况下，生成的页面包含以下形式的文本：：

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

.. autofunction:: sphinx.util.relative_uri

如果 -o 选项，则脚本将把输出文件放在 :toctree: 选择。

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

自动生成存根页面¶

如果您不想使用创建存根页面 sphinx-autogen ，您还可以使用以下配置值：

autosummary_context¶

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

传递到模板引擎上下文中的值字典，用于自动汇总存根文件。

Added in version 3.1.

autosummary_generate¶

类型:: bool
默认:: True

布尔值，指示是否扫描所有找到的文档以获取自动摘要指令，并为每个文档生成票根页。

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

新文件将放置在 :toctree: 指令的选项。

在 2.3 版本发生变更: 排放 autodoc-skip-member 活动作为 autodoc 的确如此。

在 4.0 版本发生变更: 默认情况下启用。

autosummary_generate_overwrite¶

类型:: bool
默认:: True

如果为true，则自动摘要将通过生成的存根页覆盖现有文件。

Added in version 3.0.

autosummary_mock_imports¶

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

此值包含要模拟的模块列表。看到 autodoc_mock_imports 了解更多详细信息。它默认为 autodoc_mock_imports .

Added in version 2.0.

autosummary_imported_members¶

类型:: bool
默认:: False

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

Added in version 2.1.

在 4.4 版本发生变更: 如果 autosummary_ignore_module_all 是 False 中列出的成员忽略此配置值 __all__ 。

autosummary_ignore_module_all¶

类型:: bool
默认:: True

如果 False 并且模块具有 __all__ 属性集，自动摘要记录中列出的每个成员 __all__ 没有其他人

请注意，如果中列出了导入的成员 __all__ ，它将被记录下来，而不管 autosummary_imported_members 。与…的行为相匹配 from module import * ，设置 autosummary_ignore_module_all 到假的和 autosummary_imported_members 致True。

Added in version 4.4.

autosummary_filename_map¶

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

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

Added in version 3.2.

自定义模板¶

Added in version 1.0.

您可以定制存根页面模板，方法与HTMLJJJA模板类似，请参见模板。 (TemplateBridge 不受支持。)

备注

如果您发现自己花费了大量时间来定制存根模板，这可能表明编写定制的叙述文档是一个更好的主意。

自动汇总使用以下JJJA模板文件：

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¶: 包含类的所有继承成员的名称的列表。仅适用于班级。

Added in version 1.8.0.

functions¶: 包含模块中“PUBLIC”函数名称的列表。在这里，“PUBLIC”表示名称不以下划线开头。仅适用于模块。

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

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

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

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

在 3.1 版本发生变更: 支持模块的属性。

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

Added in version 3.1.

此外，还可以使用以下过滤器

escape(s)¶: 转义要在设置RST上下文格式时使用的文本中的任何特殊字符。例如，这可以防止星号让事情变得大胆。这取代了内置的金佳 escape filter 这就实现了html转义。

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

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

备注

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

sphinx.ext.autosummary --生成自动文档摘要¶

sphinx-autogen --生成自动文档存根页面¶

自动生成存根页面¶

自定义模板¶

`sphinx.ext.autosummary` --生成自动文档摘要¶