:mod:`sphinx.ext.autosummary` -- Generate autodoc summaries
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 :mod:`sphinx.ext.autosummary` extension does this in two parts:
- There is an :rst:dir:`autosummary` directive for generating summary listings that contain links to the documented items, and short summary blurbs extracted from their docstrings.
- Optionally, the convenience script :program:`sphinx-autogen` or the new :confval:`autosummary_generate` config value can be used to generate short "stub" files for the entries listed in the :rst:dir:`autosummary` directives. These files by default contain only the corresponding :mod:`sphinx.ext.autodoc` directive, but can be customized with templates.
:program:`sphinx-autogen` -- generate autodoc stub pages
For example, the command
$ sphinx-autogen -o generated *.rst
will read all :rst:dir:`autosummary` tables in the :file:`*.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.
Generating stub pages automatically
If you do not want to create stub pages with :program:`sphinx-autogen`, you can also use this new config value:
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:
- :file:`autosummary/base.rst` -- fallback template
- :file:`autosummary/module.rst` -- template for modules
- :file:`autosummary/class.rst` -- template for classes
- :file:`autosummary/function.rst` -- template for functions
- :file:`autosummary/attribute.rst` -- template for class attributes
- :file:`autosummary/method.rst` -- template for class methods
The following variables available in the templates:
You can use the :rst:dir:`autosummary` directive in the stub pages. Stub pages are generated also based on these directives.