Sphinx

# `sphinx.ext.autosummary` – Generate autodoc summaries

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

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

  :class: class names (a list of class names, separated by spaces)

    Assign class attributes to the table. This is a common option.

    Added in version 8.2.

  :toctree: optional directory name

    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.

    Added in version 0.6.

  :caption: caption of ToC

    Add a caption to the toctree.

    Added in version 3.1.

  :signatures: format

    How to display signatures. Valid values are

    - `long` (default): use a long signature. This is still cut off so that name plus signature do not exceed a certain length.

    - `short`: Function and class signatures are displayed as `(…)` if they have arguments and as `()` if they don’t have arguments.

    - `none`: do not show signatures.

    Added in version 8.2.

  :nosignatures:

    Do not show function signatures in the summary.

    This is equivalent to `:signatures: none`.

    Added in version 0.6.

    Changed in version 8.2: The directive option is superseded by the more general `:signatures: none`.

    It will be deprecated and removed in a future version of Sphinx.

  :template: filename

    Specify a custom template for rendering the summary. 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.

    Added in version 1.0.

  :recursive:

    Generate documents for modules and sub-packages recursively. For example,

        .. autosummary::
           :recursive:

           sphinx.environment.BuildEnvironment

    Added in version 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
  Type:
    `dict[str, Any]`
  Default:
    `{}`

  A dictionary of values to pass into the template engine’s context for autosummary stubs files.

  Added in version 3.1.

autosummary_generate
  Type:
    `bool`
  Default:
    `True`

  Boolean indicating whether to scan all found documents for autosummary directives, and to generate stub pages for each.

  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.

  Changed in version 2.3: Emits `autodoc-skip-member` event as `autodoc` does.

  Changed in version 4.0: Enabled by default.

autosummary_generate_overwrite
  Type:
    `bool`
  Default:
    `True`

  If true, autosummary overwrites existing files by generated stub pages.

  Added in version 3.0.

autosummary_mock_imports
  Type:
    `list[str]`
  Default:
    `[]`

  This value contains a list of modules to be mocked up. See `autodoc_mock_imports` for more details. It defaults to `autodoc_mock_imports`.

  Added in version 2.0.

autosummary_imported_members
  Type:
    `bool`
  Default:
    `False`

  A boolean flag indicating whether to document classes and functions imported in modules.

  Added in version 2.1.

  Changed in version 4.4: If `autosummary_ignore_module_all` is `False`, this configuration value is ignored for members listed in `__all__`.

autosummary_ignore_module_all
  Type:
    `bool`
  Default:
    `True`

  If `False` and a module has the `__all__` attribute set, autosummary documents every member listed in `__all__` and no others.

  Note that if an imported member is listed in `__all__`, it will be documented regardless of the value of `autosummary_imported_members`. To match the behaviour of `from module import *`, set `autosummary_ignore_module_all` to False and `autosummary_imported_members` to True.

  Added in version 4.4.

autosummary_filename_map
  Type:
    `dict[str, str]`
  Default:
    `{}`

  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.

  Added in version 3.2.

## Customizing templates

Added 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 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 are 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.

objtype

  Type of the documented object, one of `"module"`, `"function"`, `"class"`, `"method"`, `"attribute"`, `"data"`, `"object"`, `"exception"`, `"newvarattribute"`, `"newtypedata"`, `"property"`.

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.

  Added in version 1.8.0.

functions

  List containing names of “public” functions in the module. Here, “public” 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.

  Changed in version 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.

  Added in version 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.

Note

You can use the `autosummary` directive in the stub pages. Stub pages are generated also based on these directives.

## Autolink role

:autolink:

  The `:autolink:` role functions as `:py:obj:` when the referenced name can be resolved to a Python object, and otherwise it becomes simple emphasis.

  There are some known design flaws. For example, in the case of multiple objects having the same name, `autolink` could resolve to the wrong object. It will fail silently if the referenced object is not found, for example due to a spelling mistake or renaming. This is sometimes unwanted behaviour.

  Some users choose to configure their `default_role` to `autolink` for ‘smart’ referencing using the default interpreted text role (``content``).

  See also

  `any`

  `py:obj`