sphinx.ext.autosummary – Generate autodoc summaries¶
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.
sphinx.ext.autosummary extension does this in two parts:
- There is an
autosummarydirective for generating summary listings that contain links to the documented items, and short summary blurbs extracted from their docstrings.
- Optionally, the convenience script sphinx-autogen or the new
autosummary_generateconfig value can be used to generate short “stub” files for the entries listed in the
autosummarydirectives. These files by default contain only the corresponding
sphinx.ext.autodocdirective, but can be customized with templates.
Insert a table that contains links to documented items, and a short summary blurb (the first sentence of the docstring) for each of them.
.. currentmodule:: sphinx .. autosummary:: environment.BuildEnvironment util.relative_uri
produces a table like this:
The environment in which the ReST files are translated.
.. autosummary:: :toctree: DIRNAME sphinx.environment.BuildEnvironment sphinx.util.relative_uri
toctreeoption 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
autosummaryto show function signatures in the listing, include the
.. autosummary:: :nosignatures: sphinx.environment.BuildEnvironment sphinx.util.relative_uri
You can specify a custom template with the
templateoption. For example,
.. autosummary:: :template: mytemplate.rst sphinx.environment.BuildEnvironment
New in version 1.0.
sphinx-autogen – generate autodoc stub pages¶
The sphinx-autogen script can be used to conveniently generate stub
documentation pages for items included in
For example, the command
$ sphinx-autogen -o generated *.rst
will read all
autosummary tables in the
*.rst files that have
: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
-o option is not given, the script will place the output files in the
directories specified in the
Generating stub pages automatically¶
If you do not want to create stub pages with sphinx-autogen, you can also use this new config value:
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.
New in version 1.0.
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 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 of the documented object, excluding the module and class parts.
Name of the documented object, excluding the module parts.
Full name of the documented object, including module and class parts.
Name of the module the documented object belongs to.
Name of the class the documented object belongs to. Only available for methods and attributes.
A string containing
len(full_name) * '='.
List containing names of all members of the module or class. Only available for modules and classes.
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.
List containing names of “public” classes in the module. Only available for modules.
List containing names of “public” exceptions in the module. Only available for modules.
List containing names of “public” methods in the class. Only available for classes.
List containing names of “public” attributes in the class. Only available for classes.
You can use the
autosummary directive in the stub pages.
Stub pages are generated also based on these directives.