sphinx.ext.autosummary
– 生成autodoc摘要¶
0.6 新版功能.
此扩展生成功能/方法/属性摘要列表,类似于那些输出,例如通过Epydoc和其他API doc生成工具。当您的文档字符串冗长而详细时,这一点尤其有用,并且将每个文档字符串放在单独的页面上会使它们更易于阅读。
sphinx.ext.autosummary
扩展分为两部分:
有一个
autosummary
指令,用于生成包含指向文档项的链接的摘要列表,以及从其文档字符串中提取的简短摘要模糊。可选地,方便脚本 sphinx-autogen 或 new
autosummary_generate
配置值可用于为以下列出的条目生成短 “stub ” 文件autosummary
指令。默认情况下,这些文件仅包含相应的sphinx.ext.autodoc
指令,但可以使用模板进行自定义。
-
.. autosummary::
¶ 插入一个包含文档项链接的表,以及每个文章的简短摘要blurb(文档字符串的第一句)。
autosummary
指令也可以选择作为toctree
条目包含的项目。或者,也可以自动生成这些项目的存根“.rst”文件。例如,
.. currentmodule:: sphinx .. autosummary:: environment.BuildEnvironment util.relative_uri
生成这样的表格:
environment.BuildEnvironment
([app])翻译ReST文件的环境。
util.relative_uri
(base, to)将相对URL从
base
返回到to
.Autosummary使用相同的方法预处理文档字符串和签名
autodoc-process-docstring
和autodoc-process-signature
hooks asautodoc
。选项
If you want the
autosummary
table to also serve as atoctree
entry, use thetoctree
option, for example:.. 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.If you don’t want the
autosummary
to show function signatures in the listing, include thenosignatures
option:.. autosummary:: :nosignatures: sphinx.environment.BuildEnvironment sphinx.util.relative_uri
You can specify a custom template with the
template
option. For example,.. autosummary:: :template: mytemplate.rst sphinx.environment.BuildEnvironment
would use the template
mytemplate.rst
in yourtemplates_path
to generate the pages for all entries listed. See Customizing templates below.1.0 新版功能.
sphinx-autogen – 生成autodoc存根页面¶
The sphinx-autogen script can be used to conveniently generate stub
documentation pages for items included in autosummary
listings.
例如,命令:
$ 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
自动生成存根页面¶
If you do not want to create stub pages with sphinx-autogen, you can also use these config values:
-
autosummary_generate
¶ Boolean indicating whether to scan all found documents for autosummary directives, and to generate stub pages for each.
也可以是应为其生成存根页面的文档列表。
The new files will be placed in the directories specified in the
:toctree:
options of the directives.
-
autosummary_mock_imports
¶ This value contains a list of modules to be mocked up. See
autodoc_mock_imports
for more details. It defaults toautodoc_mock_imports
.
自定义模板¶
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使用以下Jinja模板文件:
autosummary/base.rst
– 后备模板autosummary/module.rst
– 模块的模板autosummary/class.rst
– 课程模板autosummary/function.rst
– 功能模板autosummary/attribute.rst
– 类属性的模板autosummary/method.rst
– template for class methods
模板中提供以下变量:
-
name
¶ 已记录对象的名称,不包括模块和类部件。
-
objname
¶ 已记录对象的名称,不包括模块部件。
-
fullname
¶ 已记录对象的全名,包括模块和类部件。
-
module
¶ 记录的对象所属的模块的名称。
-
class
¶ Name of the class the documented object belongs to. Only available for methods and attributes.
-
underline
¶ A string containing
len(full_name) * '='
. Use theunderline
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” here 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
¶ 包含模块中 “public” 异常名称的列表。仅适用于模块。
-
methods
¶ 包含类中 “public” 方法名称的列表。仅适用于课程。
-
attributes
¶ 包含类中 “public” 属性名称的列表。仅适用于课程。
此外,还提供以下过滤器
-
escape
(s)¶ 转义要在格式化RST上下文中使用的文本中的任何特殊字符。例如,这可以防止星号使事情变得大胆。这取代了内置的 Jinja escape filter ,它可以进行 html-escaping 。
-
underline
(s, line='=') 为一段文本添加标题下划线。
例如, {{ fullname | escape | underline }}
应该用于生成页面的标题。
注解
您可以在存根页面中使用 autosummary
指令。存根页面也是基于这些指令生成的。