sphinx.ext.autosummary – Generate autodoc summaries

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:

  1. There is an autosummary directive for generating summary listings that contain links to the documented items, and short summary blurbs extracted from their docstrings.

  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::

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 when autosummary_generate is True.

For example,

.. currentmodule:: sphinx

.. autosummary::

   environment.BuildEnvironment
   util.relative_uri

produces a table like this:

environment.BuildEnvironment([app])

The environment in which the ReST files are translated.

util.relative_uri(base, to)

Return a relative URL from base to to.

Autosummary preprocesses the docstrings and signatures with the same autodoc-process-docstring and 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.

    You can also use caption option to give a caption to the toctree.

    3.1 新版功能: caption option added.

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

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 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” 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

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.