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:
There is an
autosummary
directive for generating summary listings that contain links to the documented items, and short summary blurbs extracted from their docstrings.A
autosummary
directive also generates short «stub» files for the entries listed in its content. These files by default contain only the correspondingsphinx.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 atoctree
entry for the included items. Optionally, stub.rst
files for these items can also be automatically generated whenautosummary_generate
is True.For example,
.. currentmodule:: sphinx .. autosummary:: environment.BuildEnvironment util.relative_uri
produces a table like this:
The environment in which the ReST files are translated.
util.relative_uri
(base, to)Return a relative URL from
base
toto
.Autosummary preprocesses the docstrings and signatures with the same
autodoc-process-docstring
andautodoc-process-signature
hooks asautodoc
.Opciones
- :toctree: optional directory name¶
If you want the
autosummary
table to also serve as atoctree
entry, use thetoctree
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.
Add a caption to the toctree.
Added in version 3.1.
- :nosignatures:¶
Do not show function signatures in the summary.
Added in version 0.6.
- :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 yourtemplates_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¶
A dictionary of values to pass into the template engine’s context for autosummary stubs files.
Added in version 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.Distinto en la versión 2.3: Emits
autodoc-skip-member
event asautodoc
does.Distinto en la versión 4.0: Enabled by default.
- autosummary_generate_overwrite¶
If true, autosummary overwrites existing files by generated stub pages. Defaults to true (enabled).
Added in version 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 toautodoc_mock_imports
.Added in version 2.0.
- autosummary_imported_members¶
A boolean flag indicating whether to document classes and functions imported in modules. Default is
False
Added in version 2.1.
Distinto en la versión 4.4: If
autosummary_ignore_module_all
isFalse
, this configuration value is ignored for members listed in__all__
.
- autosummary_ignore_module_all¶
If
False
and a module has the__all__
attribute set, autosummary documents every member listed in__all__
and no others. Default isTrue
Note that if an imported member is listed in
__all__
, it will be documented regardless of the value ofautosummary_imported_members
. To match the behaviour offrom module import *
, setautosummary_ignore_module_all
to False andautosummary_imported_members
to True.Added in version 4.4.
- 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.
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 Plantillas. (TemplateBridge
is not supported.)
Nota
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 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 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 theunderline
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.
Distinto en la versión 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.
Nota
You can use the autosummary
directive in the stub pages.
Stub pages are generated also based on these directives.