sphinx.ext.autosummary --生成自动生成摘要

Added in version 0.6.

此扩展生成与输出类似的函数/方法/属性摘要列表，例如通过epydoc和其他API文档生成工具生成。当您的docstrings很长而且很详细时，这尤其有用，并且将它们中的每一个放在单独的页面上会使它们更容易阅读。

这个 sphinx.ext.autosummary 扩展包括两部分：

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

  2. A autosummary 指令还为其内容中列出的条目生成简短的“存根”文件。默认情况下，这些文件仅包含对应的 sphinx.ext.autodoc 指令，但可以使用模板进行自定义。

    这个 sphinx-autogen 脚本还能够从命令行生成“存根”文件。

.. autosummary::

插入一个表，其中包含指向文档化项目的链接，并为每个项目插入一个简短的摘要Blurb（docString的第一句话）。

这个 autosummary 指令还可以作为可选的 toctree 包含项的条目。可选，存根 .rst 当 autosummary_generate 是 True .

例如：

.. currentmodule:: sphinx

.. autosummary::

   environment.BuildEnvironment
   util.relative_uri

生成这样的表：

environment.BuildEnvironment \(应用)

在其中转换其余文件的环境。

util.relative_uri(base, to)

从返回相对URL base 到 to .

自动摘要预处理具有相同文档字符串和签名的文档 autodoc-process-docstring 和 autodoc-process-signature 钩子 autodoc .

Options

  • 如果你想要 autosummary 表格也用作 toctree 进入，使用 toctree 选项，例如：

    .. autosummary::
   :toctree: DIRNAME

   sphinx.environment.BuildEnvironment
   sphinx.util.relative_uri

    这个 toctree 选项还向 sphinx-autogen 为该指令中列出的条目生成存根页的脚本。该选项接受目录名作为参数； sphinx-autogen 默认情况下，将其输出放在此目录中。如果没有给出任何参数，输出将与包含该指令的文件放在同一目录中。

    您也可以使用 caption 为目录树提供标题的选项。

    Added in version 3.1: 添加了标题选项。

  • 如果你不想 autosummary 要在列表中显示函数签名，请包括 nosignatures 选项：

    .. autosummary::
   :nosignatures:

   sphinx.environment.BuildEnvironment
   sphinx.util.relative_uri

  • 可以使用指定自定义模板 template 选择权。例如：

    .. autosummary::
   :template: mytemplate.rst

   sphinx.environment.BuildEnvironment

    将使用模板 mytemplate.rst 在你 templates_path 为列出的所有条目生成页面。见 Customizing templates 下面。

    Added in version 1.0.

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

    .. autosummary::
   :recursive:

   sphinx.environment.BuildEnvironment

    Added in version 3.1.

sphinx-autogen --生成AutoDoc存根页

这个 sphinx-autogen 脚本可用于方便地为包含在 autosummary 列表。

例如，命令：

$ sphinx-autogen -o generated *.rst

将全部阅读 autosummary 表中 *.rst 具有 :toctree: 选项集，并在目录中输出相应的存根页 generated 所有记录项目。默认情况下，生成的页面包含表单的文本：

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

.. autofunction:: sphinx.util.relative_uri

如果 -o 未提供选项，脚本将把输出文件放在 :toctree: 选项。

有关详细信息，请参阅 sphinx-autogen documentation

自动生成存根页

如果不想创建存根页 sphinx-autogen ，也可以使用这些配置值：

autosummary_context

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

Added in version 3.1.

autosummary_generate

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

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

新文件将放置在 :toctree: 指令的选项。

在 2.3 版本发生变更: 发射 autodoc-skip-member 事件为 autodoc 做。

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

autosummary_generate_overwrite

如果为true，则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__ 属性集，自动汇总记录中列出的每个成员 __all__ 也没有其他人。缺省值为 True

请注意，如果中列出了导入的成员 __all__ ，它将被记录下来，而不管 autosummary_imported_members 。与…的行为相匹配 from module import * ，设置 autosummary_ignore_module_all 到假的和 autosummary_imported_members 致True。

Added in version 4.4.

autosummary_filename_map

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

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

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

classes

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

exceptions

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

methods

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

attributes

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

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

modules

包含包中“public”模块名称的列表。仅适用于软件包模块和 recursive 选项已打开。

Added in version 3.1.

此外，还提供以下过滤器

escape(s)

转义文本中用于格式化RST上下文的任何特殊字符。例如，这样可以防止星号使事物变粗。这取代了内置的Jinja escape filter 这就是HTML转义。

underline(s, line='=')

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

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

备注

你可以使用 autosummary 存根页中的指令。存根页也基于这些指令生成。