：模式：sphinx.ext.自动摘要–生成自动文档摘要¶

Added in version 0.6.

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

模式：`sphinx.ext.自动摘要`插件分为两部分：

有一个：rst:方向：`自动总结`指令，用于生成摘要列表，其中包含文档项的链接，以及从文档字符串中提取的简短摘要简介。
autosummary 指令也为其内容中列出的条目生成简短的 “stub” 文件。这些文件默认只包含相应的 sphinx.ext.autodoc 指令，但能用模板自定义。

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

.. autosummary::¶

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

这个：rst:方向：autosummary`指令还可以作为：rst:方向：`toctree`包含项的条目。或者，当：confval:`autosummary_generate`为“True”时，也可以自动生成这些项目的存根.rst``文件。

例如：

.. currentmodule:: sphinx

.. autosummary::

   environment.BuildEnvironment
   util.relative_uri

生成如下表：

`environment.BuildEnvironment`(app)	翻译ReST文件的环境。
`util.relative_uri`(base, to)	Return a relative URL from `base` to `to`.

Autosummary使用相同的方法预处理文档字符串和签名：event:autodoc process docstring`和：event:`autodoc process signature hookas:mod:~sphinx.ext.autodoc.

选项

如果您想要：rst:方向：`autosummary`表还可以用作：rst:方向：`toctree`条目，使用`toctree``选项，例如：
```
.. autosummary::
   :toctree: DIRNAME

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

您还可以使用“caption”选项为目录树提供标题。

Added in version 3.1: caption选项已添加。
如果您不想：rst:方向：`autosummary`要在列表中显示函数签名，请包含“nosignatures”选项：
```
.. autosummary::
   :nosignatures:

   sphinx.environment.BuildEnvironment
   sphinx.util.relative_uri
```
可以使用“template”选项指定自定义模板。例如：：：
```
.. autosummary::
   :template: mytemplate.rst

   sphinx.environment.BuildEnvironment
```
将使用模板：文件：`我的模板.rst`在：confval:`templates_path`中为列出的所有条目生成页面。请参见下面的“自定义模板”。

Added in version 1.0.
您可以指定“recursive”选项以递归方式为模块和子包生成文档。默认为禁用。例如：：：
```
.. autosummary::
   :recursive:

   sphinx.environment.BuildEnvironment
```
Added in version 3.1.

：program:sphinx autogen–生成autodoc存根页¶

可以使用：program:`sphinx autogen`脚本方便地为以下项目生成存根文档页：rst:方向：`autosummary`列表。

例如，指令为：

$ sphinx-autogen -o generated *.rst

将全部读取：rst:方向file:*.rst`文件中的：autosummary`表，这些文件设置了:toctree:``选项，并为所有文档项在“generated”目录中输出相应的存根页。默认情况下，生成的页面包含以下表单的文本：

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

.. autofunction:: sphinx.util.relative_uri

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

有关详细信息，请参阅：doc:sphinx autogen文档

自动生成存根页¶

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

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

Added in version 3.1.

autosummary_generate¶

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

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

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

在 2.3 版本发生变更: 发出：事件：`autodoc skip member`事件为：mod:`~sphinx.ext.autodoc`是的。

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

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

Added in version 3.0.

autosummary_mock_imports¶: 此值包含要模拟的模块列表。有关详细信息，请参见：confval:autodoc_mock_imports’。默认为：confval:`autodoc_mock_imports。

Added in version 2.0.

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

Added in version 2.1.

在 4.4 版本发生变更: If autosummary_ignore_module_all is False, this configuration value is ignored for members listed in __all__.

autosummary_ignore_module_all¶

If False and a module has the __all__ attribute set, autosummary documents every member listed in __all__ and no others. Default is True

Note that if an imported member is listed in __all__, it will be documented regardless of the value of autosummary_imported_members. To match the behaviour of from module import *, set autosummary_ignore_module_all to False and autosummary_imported_members to True.

Added in version 4.4.

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

Added in version 3.2.

自定义模板¶

Added in version 1.0.

您可以自定义存根页模板，方法与HTML Jinja模板类似，请参见：ref:templating。（：等级：`~sphinx.application.TemplateBridge`不支持。）

备注

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

Autosummary使用以下Jinja模板文件：

：文件：autosummary/基准.rst–回退模板
：文件：autosummary/模块.rst–模块模板
：文件：autosummary/类rst–类模板
：文件：autosummary/函数.rst–函数模板
：文件：autosummary/属性.rst–类属性模板
：文件：autosummary/方法.rst–类方法模板

The following variables are available in the templates:

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

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

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

objtype¶: Type of the documented object, one of "module", "function", "class", "method", "attribute", "data", "object", "exception", "newvarattribute", "newtypedata", "property".

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

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

underline¶: 一个包含“len（全名）*’=``”的字符串。请改用“下划线”筛选器。

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

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

Added in version 1.8.0.

functions¶: List containing names of “public” functions in the module. Here, “public” means that the name does not start with an underscore. Only available for modules.

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

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

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

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

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

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

Added in version 3.1.

此外，还提供以下过滤器

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

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

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

备注

您可以使用：rst:方向存根页中的：`autosummary`指令。存根页也是基于这些指令生成的。

Sphinx

On this page

Site navigation

：模式：sphinx.ext.自动摘要–生成自动文档摘要¶

：program:sphinx autogen–生成autodoc存根页¶

自动生成存根页¶

自定义模板¶