sphinx.ext.autosummary

package documentation

sphinx.ext.autosummary ~~~~~~~~~~~~~~~~~~~~~~ Sphinx extension that adds an autosummary:: directive, which 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'. :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details.

Unknown Field: copyright
Copyright 2007-2022 by the Sphinx team, see AUTHORS.
Unknown Field: license
BSD, see LICENSE for details.

Module generate sphinx.ext.autosummary.generate ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

From __init__.py:

Constant	`WELL_KNOWN_ABBREVIATIONS`	Undocumented
Variable	`literal_re`	Undocumented
Variable	`logger`	Undocumented
Variable	`periods_re`	Undocumented
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
Class	`ImportExceptionGroup`	Exceptions raised during importing the target objects.
Function	`_cleanup_signature`	Clean up signature using inspect.signautre() for mangle_signature()
Function	`_import_by_name`	Import a Python object given its full name.
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_autosummary_toc`	Insert items described in autosummary:: to the TOC tree, but do not generate the toctree:: list.
Function	`process_generate_options`	Undocumented
Function	`setup`	Undocumented
Function	`strip_arg_typehint`	Strip a type hint from argument definition.

logger =

Undocumented

periods_re =

Undocumented

literal_re =

Undocumented

WELL_KNOWN_ABBREVIATIONS: tuple[str, ...] =

Undocumented

Value

('et al.', ' i.e.')

def process_autosummary_toc(app, doctree):

Insert items described in autosummary:: to the TOC tree, but do not generate the toctree:: list.

Parameters
app:`Sphinx`	Undocumented
doctree:`nodes.document`	Undocumented

def autosummary_toc_visit_html(self, node):

Hide autosummary toctree list in HTML output.

Parameters
node:`autosummary_toc`	Undocumented

def autosummary_noop(self, node):

Undocumented

Parameters
node:`Node`	Undocumented

def autosummary_table_visit_html(self, node):

Make the first column of the table non-breaking.

Parameters
node:`autosummary_table`	Undocumented

def get_documenter(app, obj, parent):

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:`Sphinx`	Undocumented
obj:`Any`	Undocumented
parent:`Any`	Undocumented
Returns
`Type[Documenter]`	Undocumented

def strip_arg_typehint(s):

Strip a type hint from argument definition.

Parameters
s:`str`	Undocumented
Returns
`str`	Undocumented

def _cleanup_signature(s):

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

Parameters
s:`str`	Undocumented
Returns
`str`	Undocumented

def mangle_signature(sig, max_chars=30):

Reformat a function signature to a more compact form.

Parameters
sig:`str`	Undocumented
max_chars:`int`	Undocumented
Returns
`str`	Undocumented

def extract_summary(doc, document):

Extract summary from docstring.

Parameters
doc:`List[str]`	Undocumented
document:`Any`	Undocumented
Returns
`str`	Undocumented

def limited_join(sep, items, max_chars=30, overflow_marker='...'):

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:`str`	Undocumented
items:`List[str]`	Undocumented
max_chars:`int`	Undocumented
overflow_marker:`str`	Undocumented
Returns
`str`	Undocumented

def get_import_prefixes_from_env(env):

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

Parameters
env:`BuildEnvironment`	Undocumented
Returns
`List[str]`	Undocumented

def import_by_name(name, prefixes=[None], grouped_exception=False):

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

Parameters
name:`str`	Undocumented
prefixes:`List[str]`	Undocumented
grouped_exception:`bool`	Undocumented
Returns
`Tuple[str, Any, Any, str]`	Undocumented

def _import_by_name(name, grouped_exception=False):

Import a Python object given its full name.

Parameters
name:`str`	Undocumented
grouped_exception:`bool`	Undocumented
Returns
`Tuple[Any, Any, str]`	Undocumented

def import_ivar_by_name(name, prefixes=[None], grouped_exception=False):

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

Parameters
name:`str`	Undocumented
prefixes:`List[str]`	Undocumented
grouped_exception:`bool`	Undocumented
Returns
`Tuple[str, Any, Any, str]`	Undocumented

def get_rst_suffix(app):

Undocumented

Parameters
app:`Sphinx`	Undocumented
Returns
`str`	Undocumented

def process_generate_options(app):

Undocumented

Parameters
app:`Sphinx`	Undocumented

def setup(app):

Undocumented

Parameters
app:`Sphinx`	Undocumented
Returns
`Dict[str, Any]`	Undocumented