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

Added in version 0.6.

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

The sphinx.ext.autosummary extension does this in two parts:

有一个 autosummary 指令,用于生成包含文档项目链接的摘要列表,并从它们的文档字符串中提取简短的摘要描述.
一个 autosummary 指令还会为其内容中列出的条目生成简短的”存根”文件.这些文件默认仅包含相应的 sphinx.ext.autodoc 指令,但可以通过模板进行自定义.

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

.. autosummary::¶

插入一个表格,其中包含链接到文档项目的条目,以及每个条目的简短摘要（文档字符串的第一句）.

The autosummary directive can also optionally serve as a toctree entry for the included items. Optionally, stub .rst files for these items can also be automatically generated when autosummary_generate is True.

例如,:

.. currentmodule:: sphinx

.. autosummary::

   environment.BuildEnvironment
   util.relative_uri

生成一个像这样的表格:

`环境.BuildEnvironment` (应用)	ReST 文件被转换的环境.
`util.relative_uri` (基准,至"}	从 `base` 返回到 `to` 的相对URL.

Autosummary 使用与 autodoc 相同的 autodoc-process-docstring 和 autodoc-process-signature 钩子预处理文档字符串和签名.

选项

如果您希望 autosummary 表也作为 toctree 目录的一部分,请使用 toctree 选项,例如:
```
.. autosummary::
   :toctree: DIRNAME

   sphinx.environment.BuildEnvironment
   sphinx.util.relative_uri
```
The toctree option also signals to the sphinx-autogen script that stub pages should be generated for the entries listed in this directive. The option accepts a directory name as an argument; sphinx-autogen will by default place its output in this directory. If no argument is given, output is placed in the same directory as the file that contains the directive.

您也可以使用 caption 选项为 toctree 添加标题.

Added in version 3.1: 添加了 caption 选项.

如果您不希望 :rst :dir:`autosummary` 在列表中显示函数签名,请包含 nosignatures 选项:

.. autosummary::
   :nosignatures:

   sphinx.environment.BuildEnvironment
   sphinx.util.relative_uri

您可以通过 template 选项指定自定义模板.例如,:
```
.. autosummary::
   :template: mytemplate.rst

   sphinx.environment.BuildEnvironment
```
将使用模板 mytemplate.rst 在你的 templates_path 中为所有列出的条目生成页面.请参见下面的定制模板 .

Added in version 1.0.
您可以指定 recursive 选项,以递归地为模块和子包生成文档.默认情况下此选项是禁用的.例如,:
```
.. autosummary::
   :recursive:

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

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

The sphinx-autogen script can be used to conveniently generate stub documentation pages for items included in autosummary listings.

例如,命令:

$ 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¶: 一个字典,用于将值传递到模板引擎的上下文中,以生成自动摘要存根文件.

Added in version 3.1.

autosummary_generate¶

布尔值,指示是否扫描所有找到的文档以查找自动摘要指令,并为每个指令生成存根页面.默认情况下启用.

也可以是一个文档列表,用于生成占位页面.

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

在 2.3 版本发生变更: 发出:event:autodoc-skip-member 事件,就像 autodoc 所做的那样.

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

autosummary_generate_overwrite¶: 如果为真,autosummary将通过生成的存根页面覆盖现有文件.默认为true（启用）.

Added in version 3.0.

autosummary_mock_imports¶: 此值包含要模拟的模块列表.有关更多详情,请参见 autodoc_mock_imports .默认值为 autodoc_mock_imports .

Added in version 2.0.

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

Added in version 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.

Added in version 4.4.

autosummary_filename_map¶: 一个将对象名称映射到文件名的字典.这是必要的,以避免在文件名不区分大小写的文件系统中,当多个对象的名称在忽略大小写时无法区分而导致的文件名冲突.

Added in version 3.2.

自定义模板¶

Added in version 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¶: 类的所有继承成员的名称的列表.仅适用于类.

Added in version 1.8.0.

functions¶: 包含模块中 “公共” 函数名称的列表.这里的 “公共” 意味着名称不以下划线开头.仅适用于模块.

classes¶: 包含模块中”公共”类的名称的列表.仅对模块可用.

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

methods¶: 列出类中 “公共” 方法的名称.仅适用于类.

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

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

modules¶: 包含软件包中 “公共 “模块名称的列表. 仅适用于模块是包,并且 recursive 选项已开启.

Added in version 3.1.

此外,以下筛选器可用

escape(s)¶: 转义任何要在 RST 上下文中使用的文本中的特殊字符.例如,这可以防止星号使文本加粗.这取代了内置的 Jinja escape filter ,其用于 HTML 转义.

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

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

备注

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

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

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

自动生成存根页面¶

自定义模板¶

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