rendering ¤
This module implements rendering utilities.
Classes:
-
AutorefsHook
–Autorefs hook.
Functions:
-
do_as_attributes_section
–Build an attributes section from a list of attributes.
-
do_as_classes_section
–Build a classes section from a list of classes.
-
do_as_functions_section
–Build a functions section from a list of functions.
-
do_as_modules_section
–Build a modules section from a list of modules.
-
do_crossref
–Deprecated. Filter to create cross-references.
-
do_filter_objects
–Filter a dictionary of objects based on their docstrings.
-
do_format_attribute
–Format an attribute.
-
do_format_code
–Format code.
-
do_format_signature
–Format a signature.
-
do_get_template
–Get the template name used to render an object.
-
do_multi_crossref
–Deprecated. Filter to create cross-references.
-
do_order_members
–Order members given an ordering method.
-
do_split_path
–Split object paths for building cross-references.
AutorefsHook ¤
AutorefsHook(
current_object: Object | Alias, config: PythonOptions
)
flowchart TD
mkdocstrings_handlers.python.rendering.AutorefsHook[AutorefsHook]
click mkdocstrings_handlers.python.rendering.AutorefsHook href "" "mkdocstrings_handlers.python.rendering.AutorefsHook"
Autorefs hook.
With this hook, we're able to add context to autorefs (cross-references), such as originating file path and line number, to improve error reporting.
Parameters:
-
current_object
¤Object | Alias
) –The object being rendered.
-
config
¤PythonOptions
) –The configuration dictionary.
Methods:
-
expand_identifier
–Expand an identifier.
-
get_context
–Get the context for the current object.
Attributes:
-
config
–The configuration options.
-
current_object
–The current object being rendered.
current_object instance-attribute
¤
current_object = current_object
The current object being rendered.
expand_identifier ¤
expand_identifier(identifier: str) -> str
do_as_attributes_section ¤
do_as_attributes_section(
context: Context,
attributes: Sequence[Attribute],
*,
check_public: bool = True
) -> DocstringSectionAttributes
Build an attributes section from a list of attributes.
Parameters:
-
attributes
¤Sequence[Attribute]
) –The attributes to build the section from.
-
check_public
¤bool
, default:True
) –Whether to check if the attribute is public.
Returns:
-
DocstringSectionAttributes
–An attributes docstring section.
do_as_classes_section ¤
do_as_classes_section(
context: Context,
classes: Sequence[Class],
*,
check_public: bool = True
) -> DocstringSectionClasses
do_as_functions_section ¤
do_as_functions_section(
context: Context,
functions: Sequence[Function],
*,
check_public: bool = True
) -> DocstringSectionFunctions
do_as_modules_section ¤
do_as_modules_section(
context: Context,
modules: Sequence[Module],
*,
check_public: bool = True
) -> DocstringSectionModules
do_crossref ¤
do_filter_objects ¤
do_filter_objects(
objects_dictionary: dict[str, Object | Alias],
*,
filters: Sequence[tuple[Pattern, bool]] | None = None,
members_list: bool | list[str] | None = None,
inherited_members: bool | list[str] = False,
keep_no_docstrings: bool = True
) -> list[Object | Alias]
Filter a dictionary of objects based on their docstrings.
Parameters:
-
objects_dictionary
¤dict[str, Object | Alias]
) –The dictionary of objects.
-
filters
¤Sequence[tuple[Pattern, bool]] | None
, default:None
) –Filters to apply, based on members' names. Each element is a tuple: a pattern, and a boolean indicating whether to reject the object if the pattern matches.
-
members_list
¤bool | list[str] | None
, default:None
) –An optional, explicit list of members to keep. When given and empty, return an empty list. When given and not empty, ignore filters and docstrings presence/absence.
-
inherited_members
¤bool | list[str]
, default:False
) –Whether to keep inherited members or exclude them.
-
keep_no_docstrings
¤bool
, default:True
) –Whether to keep objects with no/empty docstrings (recursive check).
Returns:
do_format_attribute ¤
do_format_attribute(
context: Context,
attribute_path: Markup,
attribute: Attribute,
line_length: int,
*,
crossrefs: bool = False
) -> str
Format an attribute.
Parameters:
-
context
¤Context
) –Jinja context, passed automatically.
-
attribute_path
¤Markup
) –The path of the callable we render the signature of.
-
attribute
¤Attribute
) –The attribute we render the signature of.
-
line_length
¤int
) –The line length.
-
crossrefs
¤bool
, default:False
) –Whether to cross-reference types in the signature.
Returns:
-
str
–The same code, formatted.
do_format_signature ¤
do_format_signature(
context: Context,
callable_path: Markup,
function: Function,
line_length: int,
*,
annotations: bool | None = None,
crossrefs: bool = False
) -> str
Format a signature.
Parameters:
-
context
¤Context
) –Jinja context, passed automatically.
-
callable_path
¤Markup
) –The path of the callable we render the signature of.
-
function
¤Function
) –The function we render the signature of.
-
line_length
¤int
) –The line length.
-
annotations
¤bool | None
, default:None
) –Whether to show type annotations.
-
crossrefs
¤bool
, default:False
) –Whether to cross-reference types in the signature.
Returns:
-
str
–The same code, formatted.
do_get_template ¤
do_multi_crossref ¤
do_order_members ¤
do_order_members(
members: Sequence[Object | Alias],
order: Order,
members_list: bool | list[str] | None,
) -> Sequence[Object | Alias]