Skip to content

rendering ¤

This module implements rendering utilities.

Classes:

  • Order –

    Enumeration for the possible members ordering.

Functions:

Order ¤


          flowchart TD
          mkdocstrings_handlers.python.rendering.Order[Order]

          

          click mkdocstrings_handlers.python.rendering.Order href "" "mkdocstrings_handlers.python.rendering.Order"

Enumeration for the possible members ordering.

Attributes:

alphabetical class-attribute instance-attribute ¤

alphabetical = 'alphabetical'

Alphabetical order.

source class-attribute instance-attribute ¤

source = 'source'

Source code order.

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:

do_as_classes_section ¤

do_as_classes_section(
    context: Context,
    classes: Sequence[Class],
    *,
    check_public: bool = True
) -> DocstringSectionClasses

Build a classes section from a list of classes.

Parameters:

  • classes ¤

    (Sequence[Class]) –

    The classes to build the section from.

  • check_public ¤

    (bool, default: True ) –

    Whether to check if the class is public.

Returns:

do_as_functions_section ¤

do_as_functions_section(
    context: Context,
    functions: Sequence[Function],
    *,
    check_public: bool = True
) -> DocstringSectionFunctions

Build a functions section from a list of functions.

Parameters:

  • functions ¤

    (Sequence[Function]) –

    The functions to build the section from.

  • check_public ¤

    (bool, default: True ) –

    Whether to check if the function is public.

Returns:

do_as_modules_section ¤

do_as_modules_section(
    context: Context,
    modules: Sequence[Module],
    *,
    check_public: bool = True
) -> DocstringSectionModules

Build a modules section from a list of modules.

Parameters:

  • modules ¤

    (Sequence[Module]) –

    The modules to build the section from.

  • check_public ¤

    (bool, default: True ) –

    Whether to check if the module is public.

Returns:

do_crossref ¤

do_crossref(path: str, *, brief: bool = True) -> Markup

Deprecated. Filter to create cross-references.

Parameters:

  • path ¤

    (str) –

    The path to link to.

  • brief ¤

    (bool, default: True ) –

    Show only the last part of the path, add full path as hover.

Returns:

  • Markup –

    Markup text.

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 using Black.

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 to give to Black.

  • crossrefs ¤

    (bool, default: False ) –

    Whether to cross-reference types in the signature.

Returns:

  • str –

    The same code, formatted.

do_format_code ¤

do_format_code(code: str, line_length: int) -> str

Format code using Black.

Parameters:

  • code ¤

    (str) –

    The code to format.

  • line_length ¤

    (int) –

    The line length to give to Black.

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 using Black.

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 to give to Black.

  • 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_get_template(obj: Object) -> str

Get the template name used to render an object.

Parameters:

Returns:

  • str –

    A template name.

do_multi_crossref ¤

do_multi_crossref(
    text: str, *, code: bool = True
) -> Markup

Deprecated. Filter to create cross-references.

Parameters:

  • text ¤

    (str) –

    The text to scan.

  • code ¤

    (bool, default: True ) –

    Whether to wrap the result in a code tag.

Returns:

  • Markup –

    Markup text.

do_order_members ¤

do_order_members(
    members: Sequence[Object | Alias],
    order: Order,
    members_list: bool | list[str] | None,
) -> Sequence[Object | Alias]

Order members given an ordering method.

Parameters:

Returns:

do_split_path ¤

do_split_path(
    path: str, full_path: str
) -> list[tuple[str, str]]

Split object paths for building cross-references.

Parameters:

  • path ¤

    (str) –

    The path to split.

Returns: