Sphinx

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

0.6 新版功能.

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

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

1. 有一个：rst:方向：`自动总结`指令，用于生成摘要列表，其中包含文档项的链接，以及从文档字符串中提取的简短摘要简介。

2. A autosummary directive also generates short “stub” files for the entries listed in its content. These files by default contain only the corresponding sphinx.ext.autodoc directive, but can be customized with templates.

   The sphinx-autogen script is also able to generate “stub” files from command line.

.. 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 signaturehookas: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”选项为目录树提供标题。

  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`中为列出的所有条目生成页面。请参见下面的“自定义模板”。

  1.0 新版功能.

• 您可以指定“recursive”选项以递归方式为模块和子包生成文档。默认为禁用。例如：：：

  .. autosummary::
     :recursive:
  
     sphinx.environment.BuildEnvironment
  

  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

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

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.

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

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

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

在 4.0 版更改: Enabled by default.

autosummary_generate_overwrite

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

3.0 新版功能.

autosummary_mock_imports

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

2.0 新版功能.

autosummary_imported_members

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

2.1 新版功能.

autosummary_filename_map

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

3.2 新版功能.

自定义模板

1.0 新版功能.

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

注解

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

Autosummary使用以下Jinja模板文件：

• ：文件：autosummary/基准.rst–回退模板

• ：文件：autosummary/模块.rst–模块模板

• ：文件：autosummary/类rst–类模板

• ：文件：autosummary/函数.rst–函数模板

• ：文件：autosummary/属性.rst–类属性模板

• ：文件：autosummary/方法.rst–类方法模板

模板中提供以下变量：

name

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

objname

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

fullname

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

module

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

class

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

underline

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

members

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

inherited_members

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

1.8.0 新版功能.

functions

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

classes

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

exceptions

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

methods

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

attributes

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

在 3.1 版更改: 支持模块属性。

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 新版功能.

此外，还提供以下过滤器

escape(s)

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

underline(s, line='=')

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

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

注解

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