sphinx.ext.autosummary

package documentation
(source)

Extension that adds an autosummary:: directive. The directive can be used to generate function/method/attribute/etc. summary lists, similar to those output eg. by Epydoc and other API doc generation tools. An :autolink: role is also provided. autosummary directive --------------------- The autosummary directive has the form:: .. autosummary:: :nosignatures: :toctree: generated/ module.function_1 module.function_2 ... and it generates an output table (containing signatures, optionally) ======================== ============================================= module.function_1(args) Summary line from the docstring of function_1 module.function_2(args) Summary line from the docstring ... ======================== ============================================= If the :toctree: option is specified, files matching the function names are inserted to the toctree with the given prefix: generated/module.function_1 generated/module.function_2 ... Note: The file names contain the module:: or currentmodule:: prefixes. .. seealso:: autosummary_generate.py autolink role ------------- The autolink role functions as ``:obj:`` when the name referred can be resolved to a Python object, and otherwise it becomes simple emphasis. This can be used as the default role to make links 'smart'.

Module generate Generates reST source files for autosummary.

From __init__.py:

Class AutoLink Smart linking role.
Class Autosummary Pretty table containing short signatures and summaries of functions etc.
Class autosummary_table Undocumented
Class autosummary_toc Undocumented
Class FakeApplication Undocumented
Class FakeDirective Undocumented
Exception ImportExceptionGroup Exceptions raised during importing the target objects.
Function autosummary_noop Undocumented
Function autosummary_table_visit_html Make the first column of the table non-breaking.
Function autosummary_toc_visit_html Hide autosummary toctree list in HTML output.
Function extract_summary Extract summary from docstring.
Function get_documenter Get an autodoc.Documenter class suitable for documenting the given object.
Function get_import_prefixes_from_env Obtain current Python import prefixes (for `import_by_name`) from ``document.env``
Function get_rst_suffix Undocumented
Function import_by_name Import a Python object that has the given *name*, under one of the *prefixes*. The first name that succeeds is used.
Function import_ivar_by_name Import an instance variable that has the given *name*, under one of the *prefixes*. The first name that succeeds is used.
Function limited_join Join a number of strings into one, limiting the length to *max_chars*.
Function mangle_signature Reformat a function signature to a more compact form.
Function process_generate_options Undocumented
Function setup Undocumented
Function strip_arg_typehint Strip a type hint from argument definition.
Constant WELL_KNOWN_ABBREVIATIONS Undocumented
Variable literal_re Undocumented
Variable logger Undocumented
Variable periods_re Undocumented
Function _cleanup_signature Clean up signature using inspect.signautre() for mangle_signature()
Function _import_by_name Import a Python object given its full name.
logger = (source)

Undocumented

periods_re = (source)

Undocumented

literal_re = (source)

Undocumented

WELL_KNOWN_ABBREVIATIONS: tuple[str, ...] = (source)

Undocumented

Value
('et al.', ' i.e.')
def autosummary_toc_visit_html(self, node): (source)

Hide autosummary toctree list in HTML output.

Parameters
self:nodes.NodeVisitorUndocumented
node:autosummary_tocUndocumented
def autosummary_noop(self, node): (source)

Undocumented

Parameters
self:nodes.NodeVisitorUndocumented
node:NodeUndocumented
def autosummary_table_visit_html(self, node): (source)

Make the first column of the table non-breaking.

Parameters
self:HTML5TranslatorUndocumented
node:autosummary_tableUndocumented
def get_documenter(app, obj, parent): (source)

Get an autodoc.Documenter class suitable for documenting the given object. *obj* is the Python object to be documented, and *parent* is an another Python object (e.g. a module or a class) to which *obj* belongs to.

Parameters
app:SphinxUndocumented
obj:AnyUndocumented
parent:AnyUndocumented
Returns
type[Documenter]Undocumented
def strip_arg_typehint(s): (source)

Strip a type hint from argument definition.

Parameters
s:strUndocumented
Returns
strUndocumented
def _cleanup_signature(s): (source)

Clean up signature using inspect.signautre() for mangle_signature()

Parameters
s:strUndocumented
Returns
strUndocumented
def mangle_signature(sig, max_chars=30): (source)

Reformat a function signature to a more compact form.

Parameters
sig:strUndocumented
max_chars:intUndocumented
Returns
strUndocumented
def extract_summary(doc, document): (source)

Extract summary from docstring.

Parameters
doc:list[str]Undocumented
document:AnyUndocumented
Returns
strUndocumented
def limited_join(sep, items, max_chars=30, overflow_marker='...'): (source)

Join a number of strings into one, limiting the length to *max_chars*. If the string overflows this limit, replace the last fitting item by *overflow_marker*. Returns: joined_string

Parameters
sep:strUndocumented
items:list[str]Undocumented
max_chars:intUndocumented
overflow_marker:strUndocumented
Returns
strUndocumented
def get_import_prefixes_from_env(env): (source)

Obtain current Python import prefixes (for `import_by_name`) from ``document.env``

Parameters
env:BuildEnvironmentUndocumented
Returns
list[str|None]Undocumented
def import_by_name(name, prefixes=[None], grouped_exception=True): (source)

Import a Python object that has the given *name*, under one of the *prefixes*. The first name that succeeds is used.

Parameters
name:strUndocumented
prefixes:list[str|None]Undocumented
grouped_exception:boolUndocumented
Returns
tuple[str, Any, Any, str]Undocumented
def _import_by_name(name, grouped_exception=True): (source)

Import a Python object given its full name.

Parameters
name:strUndocumented
grouped_exception:boolUndocumented
Returns
tuple[Any, Any, str]Undocumented
def import_ivar_by_name(name, prefixes=[None], grouped_exception=True): (source)

Import an instance variable that has the given *name*, under one of the *prefixes*. The first name that succeeds is used.

Parameters
name:strUndocumented
prefixes:list[str|None]Undocumented
grouped_exception:boolUndocumented
Returns
tuple[str, Any, Any, str]Undocumented
def get_rst_suffix(app): (source)

Undocumented

Parameters
app:SphinxUndocumented
Returns
str|NoneUndocumented
def process_generate_options(app): (source)

Undocumented

Parameters
app:SphinxUndocumented
def setup(app): (source)

Undocumented

Parameters
app:SphinxUndocumented
Returns
dict[str, Any]Undocumented