rest
sphinx.ext.autosummary
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 :rst
autosummary
directive for generating summary listings that contain links to the documented items, and short summary blurbs extracted from their docstrings. A :rst
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.
The sphinx-autogen
script can be used to conveniently generate stub documentation pages for items included in :rstautosummary
listings.
For example, the command :
$ sphinx-autogen -o generated *.rst
will read all :rstautosummary
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
</man/sphinx-autogen>
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 ~sphinx.ext.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
4.4
If autosummary_ignore_module_all
is False
, 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 is True
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.
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.
3.2
1.0
You can customize the stub page templates, in a similar way as the HTML Jinja templates, see templating
. (~sphinx.application.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 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:
None
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.
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.
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.
Note
You can use the :rstautosummary
directive in the stub pages. Stub pages are generated also based on these directives.