autodoc2.render.base#

Convert the database items into documentation.

Module Contents#

Classes#

RendererBase

The base renderer.

API#

class autodoc2.render.base.RendererBase(db: autodoc2.db.Database, config: autodoc2.config.Config, *, warn: Callable[[str, autodoc2.utils.WarningSubtypes], None] | None = None, all_resolver: autodoc2.resolve_all.AllResolver | None = None, standalone: bool = True)[source]#

Bases: abc.ABC

The base renderer.

Initialization

Initialise the renderer.

Parameters:

  • db – The database to obtain objects from.

  • config – The configuration.

  • warn – The function to use to log warnings.

  • all_resolver – The resolver to use, for following __all__ children.

  • standalone – If True, this renderer is being used to create a standalone document

EXTENSION: ClassVar[str] = '.txt'#

The extension for the output files.

_is_hidden_cache: collections.OrderedDict[str, bool] = 'OrderedDict(...)'#

Cache for the is_hidden function: full_name -> bool.

property config: autodoc2.config.Config#

The configuration.

property standalone: bool#

If True, this renderer is being used to create a standalone document.

warn(msg: str, type_: autodoc2.utils.WarningSubtypes = WarningSubtypes.RENDER_ERROR) → None[source]#

Warn the user.

get_item(full_name: str) → autodoc2.utils.ItemData | None[source]#

Get an item from the database, by full_name.

get_children(item: autodoc2.utils.ItemData, types: None | set[str] = None, *, omit_hidden: bool = True) → Iterable[autodoc2.utils.ItemData][source]#

Get the children of this item, sorted according to the config.

If module and full_name in module_all_regexes, it will use the __all__ list instead of the children.

Parameters:

  • item – The item to get the children of.

  • types – If given, only return items of these types.

  • omit_hidden – If True, omit hidden items.

is_hidden(item: autodoc2.utils.ItemData) → bool[source]#

Whether this object should be displayed in documentation.

Based on configuration regarding:

  • does i match a hidden regex pattern

  • does it have documentation

  • is it a dunder, i.e. __name__

  • is it a private member, i.e. starts with _, but not a dunder

  • is it an inherited member of a class

is_module_deprecated(item: autodoc2.utils.ItemData) → bool[source]#

Whether this module is deprecated.

no_index(item: autodoc2.utils.ItemData) → bool[source]#

Whether this item should be excluded from search engines.

show_module_summary(item: autodoc2.utils.ItemData) → bool[source]#

Whether to show a summary for this module/package.

show_class_inheritance(item: autodoc2.utils.ItemData) → bool[source]#

Whether to show the inheritance for this class.

show_annotations(item: autodoc2.utils.ItemData) → bool[source]#

Whether to show type annotations.

show_docstring(item: autodoc2.utils.ItemData) → bool[source]#

Whether to show the docstring.

abstract render_item(full_name: str) → Iterable[str][source]#

Yield the content for a single item.

format_args(args_info: autodoc2.utils.ARGS_TYPE, include_annotations: bool = True, ignore_self: None | str = None) → str[source]#

Format the arguments of a function or method.

format_annotation(annotation: None | str) → str[source]#

Format a single type annotation.

format_base(base: None | str) → str[source]#

Format a single class base type.

get_doc_parser(full_name: str) → str[source]#

Get the parser for the docstring of this item.

Returns “” if it should be parsed using the current parser.

abstract generate_summary(objects: list[autodoc2.utils.ItemData], alias: dict[str, str] | None = None) → Iterable[str][source]#

Generate a summary of the objects.

Parameters:

  • objects – A list of fully qualified names.

  • alias – A mapping of fully qualified names to a display alias.