sphinx.ext.autosummary -- 生成 autodoc 摘要

在 0.6 版本加入.

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

sphinx.ext.autosummary 插件将此分两部分处理：

  1. autosummary 指令，用于生成摘要列表，其中包含文档项的链接，以及从文档字符串中提取的简短摘要简介。

  2. autosummary 指令也为其内容中列出的条目生成简短的"stub"文件。这些文件默认只包含相应的 sphinx.ext.autodoc 指令，但能用模板自定义。

    sphinx-autogen 脚本也能够从命令行生成"stub"文件。

.. 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 (a list of class names, separated by spaces)

将 class attributes 分配给表。这是一个 常用选项 。

在 8.2 版本加入.

:toctree: optional directory name

如果您想要 autosummary 表还可以用作 toctree 的条目，使用 toctree 选项，例如：

.. autosummary::
   :toctree: DIRNAME

   sphinx.environment.BuildEnvironment
   sphinx.util.relative_uri

toctree 选项告知 sphinx-autogen 脚本，应该为该指令中列出的条目生成存根页。该选项接受一个目录名作为参数; sphinx-autogen 默认会将其输出放在此目录中。如果没有给定参数，则输出将与包含指令的文件放在同一目录中。

在 0.6 版本加入.

:caption: caption of ToC

为 toctree 添加标题。

在 3.1 版本加入.

:signatures: format

如何显示签名。有效值为

  • long （ 默认 ）：使用长签名。该签名仍然会被截断，以使名称加签名不超过一定长度。

  • short ：如果函数和类有参数，则显示为 (…)，如果没有参数，则显示为 () 。

  • none ：不显示签名。

在 8.2 版本加入.

:nosignatures:

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

这等同于 :signatures: none 。

在 0.6 版本加入.

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

它将在Sphinx的未来版本中被弃用和移除。

:template: filename

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

.. autosummary::
   :template: mytemplate.rst

   sphinx.environment.BuildEnvironment

将使用在 templates_path 中的模板 mytemplate.rst 来为所有条目生成页面。请参见下面的 Customizing templates 。

在 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 documentation

自动生成存根页

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

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

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

在 3.1 版本加入.

autosummary_generate
类型:
bool
默认:
True

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

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

新文件将被放置在指令的 :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]
默认:
{}

将对象名映射到文件名的dict。在文件名不区分大小写的文件系统中，如果多个对象的名称不区分大小写，则有必要避免文件名冲突。

在 3.2 版本加入.

自定义模板

在 1.0 版本加入.

您可以自定义存根页模板，方法与HTML Jinja模板类似，请参见 模板。（TemplateBridge 不支持。）

备注

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

Autosummary使用以下Jinja模板文件：

  • autosummary/base.rst -- fallback template

  • autosummary/module.rst -- template for modules

  • autosummary/class.rst -- template for classes

  • autosummary/function.rst -- template for functions

  • autosummary/attribute.rst -- template for class attributes

  • autosummary/method.rst -- template for class methods

模板中可用以下变量：

name

文档化对象的名称，不包括模块和类部件。

objname

记录对象的名称，不包括模块部件。

fullname

文档化对象的全名，包括模块和类部件。

objtype

记录对象的类型之一 "module"、"function"、"class"、"method"、"attribute"、"data"、"object"、"exception"、"newvarattribute"、"newtypedata"、"property" 。

module

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

class

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

underline

一个包含 len（全名）* '=' 的字符串。请改用 下划线 筛选器。

members

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

inherited_members

包含类的所有继承成员的名称的列表。仅适用于课程。

在 1.8.0 版本加入.

functions

包含模块中“public”函数名称的列表。在这里，“public”意味着名称不以下划线开头。仅适用于模块。

classes

包含模块中“public”类名称的列表。仅适用于模块。

exceptions

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

methods

包含类中“public”方法名称的列表。仅适用于课程。

attributes

包含类/模块中“public”属性名称的列表。仅适用于类和模块。

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

modules

列表包含包中的"public" 的模块名称。只适用于属于包的模块，并且 recursive 选项是开启的。

在 3.1 版本加入.

此外，还提供以下过滤器

escape(s)

对文本中要用于格式化RST上下文的任何特殊字符进行转义。例如，这可以防止星号将内容加粗。这将替换执行html转义的内置Jinja escape filter 。

underline(s, line='=')

在文本中添加标题下划线。

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

备注

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