`sphinx.ext.autosummary` —— 生成 autodoc 的摘要¶

0.6 新版功能.

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

sphinx.ext.autosummary 插件分两部分进行：

有一个 autosummary 指令，用于生成摘要列表，其中包含指向被记录的项目的链接，以及从其文档说明中提取的简短摘要。
一个 autosummary 指令也为其内容中列出的条目生成简短的 “stub” 文件。这些文件默认只包含相应的 sphinx.ext.autodoc 指令，但可以用模板定制。

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

.. autosummary::¶

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

autosummary 指令也可以选择作为 toctree 条目，用于包含的项目。当 autosummary_generate 为 True 时，这些项目的 stub .rst 文件也可以选择自动生成。

例如

.. currentmodule:: sphinx

.. autosummary::

   environment.BuildEnvironment
   util.relative_uri

产生一个类似这样的表格：

environment.BuildEnvironment([app])

翻译 ReST 文件的 environment。

util.relative_uri(base, to)

返回一个从 base 到 to 的相对 URL。

Autosummary 预处理文档字符串和签名，与 autodoc 的钩子一样，都是 autodoc-process-docstring 和 autodoc-process-signature。

选项

如果你想让 autosummary 表也作为 toctree 条目，使用 toctree 选项，例如
```
.. autosummary::
   :toctree: DIRNAME

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

你也可以使用 caption 选项来给 toctree 加一个标题。

3.1 新版功能: 增加了 caption 选项。

如果你不希望 autosummary 在列表中显示函数签名，请包括 nosignatures 选项

.. autosummary::
   :nosignatures:

   sphinx.environment.BuildEnvironment
   sphinx.util.relative_uri

你可以用 template 选项指定一个自定义模板。例如
```
.. autosummary::
   :template: mytemplate.rst

   sphinx.environment.BuildEnvironment
```
would use the template mytemplate.rst in your templates_path to generate the pages for all entries listed. See Customizing templates below.

1.0 新版功能.
You can specify the recursive option to generate documents for modules and sub-packages recursively. It defaults to disabled. For example,
```
.. autosummary::
   :recursive:

   sphinx.environment.BuildEnvironment
```
3.1 新版功能.

sphinx-autogen – generate autodoc stub pages¶

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

For example, the command

$ sphinx-autogen -o generated *.rst

will read all autosummary tables in the *.rst files that have the :toctree: option set, and output corresponding stub pages in directory generated for all documented items. The generated pages by default contain text of the form:

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

.. autofunction:: sphinx.util.relative_uri

If the -o option is not given, the script will place the output files in the directories specified in the :toctree: options.

For more information, refer to the sphinx-autogen documentation

Generating stub pages automatically¶

If you do not want to create stub pages with sphinx-autogen, you can also use these config values:

autosummary_context¶: A dictionary of values to pass into the template engine’s context for autosummary stubs files.

3.1 新版功能.

autosummary_generate¶

Boolean indicating whether to scan all found documents for autosummary directives, and to generate stub pages for each. It is enabled by default.

Can also be a list of documents for which stub pages should be generated.

The new files will be placed in the directories specified in the :toctree: options of the directives.

在 2.3 版更改: Emits autodoc-skip-member event as autodoc does.

在 4.0 版更改: Enabled by default.

autosummary_generate_overwrite¶: If true, autosummary overwrites existing files by generated stub pages. Defaults to true (enabled).

3.0 新版功能.

autosummary_mock_imports¶: This value contains a list of modules to be mocked up. See autodoc_mock_imports for more details. It defaults to autodoc_mock_imports.

2.0 新版功能.

autosummary_imported_members¶: A boolean flag indicating whether to document classes and functions imported in modules. Default is False

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.

4.4 新版功能.

autosummary_filename_map¶: A dict mapping object names to filenames. This is necessary to avoid filename conflicts where multiple objects have names that are indistinguishable when case is ignored, on file systems where filenames are case-insensitive.

3.2 新版功能.

Customizing templates¶

1.0 新版功能.

You can customize the stub page templates, in a similar way as the HTML Jinja templates, see 主题化. (TemplateBridge is not supported.)

备注

If you find yourself spending much time tailoring the stub templates, this may indicate that it’s a better idea to write custom narrative documentation instead.

Autosummary uses the following Jinja template files:

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

The following variables are available in the templates:

name¶: Name of the documented object, excluding the module and class parts.

objname¶: Name of the documented object, excluding the module parts.

fullname¶: Full name of the documented object, including module and class parts.

module¶: Name of the module the documented object belongs to.

class¶: Name of the class the documented object belongs to. Only available for methods and attributes.

underline¶: A string containing len(full_name) * '='. Use the underline filter instead.

members¶: List containing names of all members of the module or class. Only available for modules and classes.

inherited_members¶: List containing names of all inherited members of class. Only available for classes.

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¶: List containing names of “public” classes in the module. Only available for modules.

exceptions¶: List containing names of “public” exceptions in the module. Only available for modules.

methods¶: List containing names of “public” methods in the class. Only available for classes.

attributes¶: List containing names of “public” attributes in the class/module. Only available for classes and modules.

在 3.1 版更改: Attributes of modules are supported.

modules¶: List containing names of “public” modules in the package. Only available for modules that are packages and the recursive option is on.

3.1 新版功能.

Additionally, the following filters are available

escape(s)¶: Escape any special characters in the text to be used in formatting RST contexts. For instance, this prevents asterisks making things bold. This replaces the builtin Jinja escape filter that does html-escaping.

underline(s, line='='): Add a title underline to a piece of text.

For instance, {{ fullname | escape | underline }} should be used to produce the title of a page.

备注

You can use the autosummary directive in the stub pages. Stub pages are generated also based on these directives.

目录

上一个主题

下一个主题

本页

`sphinx.ext.autosummary` —— 生成 autodoc 的摘要¶

sphinx-autogen – generate autodoc stub pages¶

Generating stub pages automatically¶

Customizing templates¶

`environment.BuildEnvironment`([app])	翻译 ReST 文件的 environment。
`util.relative_uri`(base, to)	返回一个从 `base` 到 `to` 的相对 URL。

sphinx.ext.autosummary —— 生成 autodoc 的摘要¶

sphinx-autogen – generate autodoc stub pages¶

Generating stub pages automatically¶

Customizing templates¶

`sphinx.ext.autosummary` —— 生成 autodoc 的摘要¶