发布于 2015-09-16 15:38:44 | 414 次阅读 | 评论: 0 | 来源: 网络整理
New in version 0.6.
This extension generates function/method/attribute summary lists, similar to those output e.g. by Epydoc and other API doc generation tools. This is especially useful when your docstrings are long and detailed, and putting each one of them on a separate page makes them easier to read.
The sphinx.ext.autosummary extension does this in two parts:
autosummary directive for generating summary listings that contain links to the documented items, and short summary blurbs extracted from their docstrings.autosummary directives. These files by default contain only the corresponding sphinx.ext.autodoc directive, but can be customized with templates... autosummary::Insert a table that contains links to documented items, and a short summary blurb (the first sentence of the docstring) for each of them.
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.
For example,
.. currentmodule:: sphinx
.. autosummary::
environment.BuildEnvironment
util.relative_uri
produces a table like this:
Autosummary preprocesses the docstrings and signatures with the same :event:`autodoc-process-docstring` and :event:`autodoc-process-signature` hooks as autodoc.
Options
If you want the autosummary table to also serve as a toctree entry, use the toctree 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 the nosignatures 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 your :confval:`templates_path` to generate the pages for all entries listed. See Customizing templates below.
New in version 1.0.
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.
If you do not want to create stub pages with sphinx-autogen, you can also use this new config value:
New in version 1.0.
You can customize the stub page templates, in a similar way as the HTML Jinja templates, see Templating. (TemplateBridge is not supported.)
Note
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 template files:
autosummary/base.rst – fallback templateautosummary/module.rst – template for modulesautosummary/class.rst – template for classesautosummary/function.rst – template for functionsautosummary/attribute.rst – template for class attributesautosummary/method.rst – template for class methodsThe following variables available in the templates:
nameName of the documented object, excluding the module and class parts.
objnameName of the documented object, excluding the module parts.
fullnameFull name of the documented object, including module and class parts.
moduleName of the module the documented object belongs to.
className of the class the documented object belongs to. Only available for methods and attributes.
underlineA string containing len(full_name) * '='.
membersList containing names of all members of the module or class. Only available for modules and classes.
functionsList 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.
classesList containing names of “public” classes in the module. Only available for modules.
exceptionsList containing names of “public” exceptions in the module. Only available for modules.
methodsList containing names of “public” methods in the class. Only available for classes.
attributesList containing names of “public” attributes in the class. Only available for classes.
Note
You can use the autosummary directive in the stub pages. Stub pages are generated also based on these directives.