more_autosummary

Extensions to sphinx.ext.autosummary.

Provides an enhanced version of https://autodocsumm.readthedocs.io/ which respects the autodoc member-order option. This can be given for an individual directive, in the autodoc_member_order configuration value, or via autodocsumm_member_order.

Also patches sphinx.ext.autosummary.Autosummary to fix an issue where the module name is sometimes duplicated. I.e. foo.bar.baz() became foo.bar.foo.bar.baz(), which of course doesn’t exist and created a broken link.

New in version 0.7.0.

Changed in version 1.3.0: Autosummary now selects the appropriate documenter for attributes rather than falling back to DataDocumenter.

Changed in version 2.13.0: Also patches sphinx.ext.autodoc.ModuleDocumenter to fix an issue where __all__ is not respected for autosummary tables.

Configuration

autodocsumm_member_order
Type: str
Default: 'alphabetical'

Determines the sort order of members in autodocsumm summary tables. Valid values are 'alphabetical' and 'bysource'.

Note that for 'bysource' the module must be a Python module with the source code available.

The member order can also be set on a per-directive basis using the :member-order: [order] option. This applies not only to automodule etc. directives, but also to automodulesumm etc. directives.

autosummary_col_type
Type: str
Default: '\X'

The LaTeX column type to use for autosummary tables.

Custom columns can be defined in the LaTeX preamble for use with this option.

For example:

latex_elements["preamble"] = r'''
    \makeatletter
    \newcolumntype{\Xx}[2]{>{\raggedright\arraybackslash}p{\dimexpr
        (\linewidth-\arrayrulewidth)*#1/#2-\tw@\tabcolsep-\arrayrulewidth\relax}}
    \makeatother
    '''

autosummary_col_type = "\\Xx"

New in version 2.13.0.

API Reference

Classes:

PatchedAutoSummClassDocumenter(*args)

Patched version of autodocsumm.AutoSummClassDocumenter which doesn’t show summary tables for aliased objects.

PatchedAutoSummModuleDocumenter(*args)

Patched version of autodocsumm.AutoSummClassDocumenter which works around a bug in Sphinx 3.4 and above where __all__ is not respected.

PatchedAutosummary(name, arguments, options, …)

Pretty table containing short signatures and summaries of functions etc.

Functions:

get_documenter(app, obj, parent)

Returns an autodoc.Documenter class suitable for documenting the given object.

setup(app)

Setup sphinx_toolbox.more_autosummary.
class PatchedAutoSummClassDocumenter(*args)[source]

Bases: AutoSummClassDocumenter

Patched version of autodocsumm.AutoSummClassDocumenter which doesn’t show summary tables for aliased objects.

New in version 0.9.0.

Methods:

add_content(*args, **kwargs)

Add content from docstrings, attribute documentation and user.
add_content(*args, **kwargs)[source]

Add content from docstrings, attribute documentation and user.

class PatchedAutoSummModuleDocumenter(*args)[source]

Bases: AutoSummModuleDocumenter

Patched version of autodocsumm.AutoSummClassDocumenter which works around a bug in Sphinx 3.4 and above where __all__ is not respected.

New in version 2.13.0.

class PatchedAutosummary(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: Autosummary

Pretty table containing short signatures and summaries of functions etc.

Patched version of sphinx.ext.autosummary.Autosummary to fix an issue where the module name is sometimes duplicated.

I.e. foo.bar.baz() became foo.bar.foo.bar.baz(), which of course doesn’t exist and created a broken link.

New in version 0.5.1.

Changed in version 0.7.0: Moved from sphinx_toolbox.patched_autosummary.

Changed in version 2.13.0: Added support for customising the column type with the autosummary_col_type option.

Methods:

create_documenter(app, obj, parent, full_name)

Get an autodoc.Documenter class suitable for documenting the given object.

get_table(items)

Generate a list of table nodes for the autosummary directive.

import_by_name(name, prefixes)

Import the object with the give name.
create_documenter(app, obj, parent, full_name)[source]

Get an autodoc.Documenter class suitable for documenting the given object.

Parameters

  • app (Sphinx) – The Sphinx application.

  • obj (Any) – The object being documented.

  • parent (Any) – The parent of the object (e.g. a module or a class).

  • full_name (str) – The full name of the object.

Changed in version 1.3.0: Now selects the appropriate documenter for attributes rather than falling back to DataDocumenter.

Return type

Documenter

get_table(items)[source]

Generate a list of table nodes for the autosummary directive.

Parameters

items (List[Tuple[str, str, str, str]]) – A list produced by self.get_items.

Return type

List[Node]

import_by_name(name, prefixes)[source]

Import the object with the give name.

Parameters
Return type

Tuple[str, Any, Any, str]

Returns

The real name of the object, the object, the parent of the object, and the name of the module.

get_documenter(app, obj, parent)[source]

Returns an autodoc.Documenter class suitable for documenting the given object.

New in version 1.3.0.

Parameters

  • app (Sphinx) – The Sphinx application.

  • obj (Any) – The object being documented.

  • parent (Any) – The parent of the object (e.g. a module or a class).

Return type

Type[Documenter]

setup(app)[source]

Setup sphinx_toolbox.more_autosummary.

Parameters

app (Sphinx) – The Sphinx application.

Return type

SphinxExtMetadata