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

0.6 版本新增。

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

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

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

  2. 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: 类名 （以空格分隔的类名列表）

将 类属性 分配给表格。这是一个 通用选项。

8.2 版本新增。

:toctree: 可选目录名

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

.. autosummary::
   :toctree: DIRNAME

   sphinx.environment.BuildEnvironment
   sphinx.util.relative_uri

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

0.6 版本新增。

:caption: 目录的标题

为目录添加标题。

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 – 生成自动文档存根页面

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 指令。存根页面也是根据这些指令生成的。