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 toautomodule
etc. directives, but also toautomodulesumm
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:
Patched version of |
|
Patched version of |
|
|
Pretty table containing short signatures and summaries of functions etc. |
Functions:
|
Returns an |
|
- 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.
- 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()
becamefoo.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
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.
- get_documenter(app, obj, parent)[source]¶
Returns an
autodoc.Documenter
class suitable for documenting the given object.New in version 1.3.0.
- setup(app)[source]¶
Setup
sphinx_toolbox.more_autosummary
.- Parameters
app (
Sphinx
) – The Sphinx application.- Return type