CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-mkdocstrings-python

A Python handler for mkdocstrings that generates API documentation from source code using Griffe.

—

Pending
Overview
Eval results
Files

rendering.mddocs/

Rendering and Template Functions

Template functions and utilities for formatting code signatures, handling cross-references, organizing documentation output, and controlling the presentation of Python API documentation.

Note: Most rendering functions are Jinja2 template filters that receive a context parameter automatically. The signatures below show the user-visible parameters only.

Capabilities

Code Formatting Functions

Functions for formatting Python code signatures and snippets with appropriate line length and style.

def do_format_code(code: str, line_length: int = 88) -> str:
    """
    Format code snippets with appropriate line wrapping.
    
    Parameters:
    - code: str - The code to format
    - line_length: int - Maximum line length (default: 88)
    
    Returns:
    str - Formatted code with proper line breaks
    """

def do_format_signature(
    callable_path: str,
    function: object,
    line_length: int,
    *,
    annotations: bool | None = None,
    crossrefs: bool = False
) -> str:
    """
    Format function/method signatures for display.
    
    Parameters:
    - callable_path: str - Path to the callable object
    - function: object - Function object to format
    - line_length: int - Maximum line length
    - annotations: bool | None - Whether to show type annotations (optional)
    - crossrefs: bool - Whether to generate cross-references (default: False)
    
    Returns:
    str - Formatted signature with proper line breaks
    """

def do_format_attribute(
    attribute_path: str,
    attribute: object,
    line_length: int,
    *,
    crossrefs: bool = False,
    show_value: bool = True
) -> str:
    """
    Format attribute signatures for display.
    
    Parameters:
    - attribute_path: str - Path to the attribute object  
    - attribute: object - Attribute object to format
    - line_length: int - Maximum line length
    - crossrefs: bool - Whether to generate cross-references (default: False)
    - show_value: bool - Whether to show the attribute value (default: True)
    
    Returns:
    str - Formatted attribute signature
    """

def do_format_type_alias(
    type_alias: str,
    line_length: int = 60
) -> str:
    """
    Format type alias definitions for display.
    
    Parameters:
    - type_alias: str - The type alias to format
    - line_length: int - Maximum line length (default: 60)
    
    Returns:
    str - Formatted type alias definition
    """

Usage Example:

# In a Jinja2 template
{{ signature | do_format_signature(80) }}
{{ code_block | do_format_code(100) }}

Cross-Reference Functions

Functions for generating and managing cross-references between documentation objects.

def do_crossref(path: str, *, brief: bool = True) -> Markup:
    """
    Generate cross-references to documentation objects.
    
    Parameters:
    - path: str - Dotted path to the target object
    - brief: bool - Whether to use brief reference format (default: True)
    
    Returns:
    str - HTML markup for the cross-reference
    """

def do_multi_crossref(text: str, *, code: bool = True) -> str:
    """
    Handle multiple cross-references in text content.
    
    Parameters:
    - text: str - Text containing cross-reference patterns
    - code: bool - Whether to wrap references in code tags (default: True)
    
    Returns:
    str - Text with cross-references converted to HTML links
    """

def do_stash_crossref(
    path: str,
    identifier: str
) -> str:
    """
    Stash cross-references for later processing.
    
    Parameters:
    - path: str - Path to the referenced object
    - identifier: str - Unique identifier for the reference
    
    Returns:
    str - Stashed reference placeholder
    """

def do_split_path(
    path: str,
    full_path: str
) -> list[tuple[str, str, str, str]]:
    """
    Split object paths for navigation and display.
    
    Parameters:
    - path: str - Object path to split
    - full_path: str - Full path context
    
    Returns:
    list[tuple[str, str, str, str]] - Split path components
    """

Usage Example:

# In Python code or templates
crossref_html = do_crossref("numpy.array", brief=False)
processed_text = do_multi_crossref("See `numpy.array` and `pandas.DataFrame`")

Object Organization Functions

Functions for filtering, ordering, and organizing documentation objects.

def do_filter_objects(
    objects_dictionary: dict[str, object],
    *,
    filters: Sequence[tuple[Pattern, bool]] | Literal["public"] | None = None,
    members_list: bool | list[str] | None = None,
    inherited_members: bool | list[str] = False,
    keep_no_docstrings: bool = True
) -> list[object]:
    """
    Filter objects based on inclusion/exclusion patterns.
    
    Parameters:
    - objects_dictionary: dict[str, object] - Dictionary of objects to filter
    - filters: Filter patterns (compiled regex patterns) or "public" literal
    - members_list: Specific members to include or boolean for all
    - inherited_members: Whether to include inherited members  
    - keep_no_docstrings: Whether to keep objects without docstrings
    
    Returns:
    list[object] - Filtered list of objects
    """

def do_order_members(
    members: list,
    order: Order
) -> list:
    """
    Order object members according to specified criteria.
    
    Parameters:
    - members: list - List of member objects to order
    - order: Order - Ordering method ("alphabetical", "source", "__all__")
    
    Returns:
    list - Ordered list of members
    """

Usage Example:

# Filter private members
filtered = do_filter_objects(all_members, ["!^_[^_]"])

# Order alphabetically
ordered = do_order_members(members, "alphabetical")

Section Rendering Functions

Functions for rendering different types of objects as documentation sections.

def do_as_attributes_section(
    attributes: list,
    **kwargs
) -> str:
    """
    Render attributes as a documentation section.
    
    Parameters:
    - attributes: list - List of attribute objects
    - **kwargs: Additional rendering options
    
    Returns:
    str - Rendered HTML section
    """

def do_as_functions_section(
    functions: list,
    **kwargs
) -> str:
    """
    Render functions as a documentation section.
    
    Parameters:
    - functions: list - List of function objects
    - **kwargs: Additional rendering options
    
    Returns:
    str - Rendered HTML section
    """

def do_as_classes_section(
    classes: list,
    **kwargs
) -> str:
    """
    Render classes as a documentation section.
    
    Parameters:
    - classes: list - List of class objects
    - **kwargs: Additional rendering options
    
    Returns:
    str - Rendered HTML section
    """

def do_as_modules_section(
    modules: list,
    **kwargs
) -> str:
    """
    Render modules as a documentation section.
    
    Parameters:
    - modules: list - List of module objects
    - **kwargs: Additional rendering options
    
    Returns:
    str - Rendered HTML section
    """

def do_as_type_aliases_section(
    type_aliases: list,
    **kwargs
) -> str:
    """
    Render type aliases as a documentation section.
    
    Parameters:
    - type_aliases: list - List of type alias objects
    - **kwargs: Additional rendering options
    
    Returns:
    str - Rendered HTML section
    """

Template and Navigation Functions

Functions for template management and navigation structure generation.

def do_get_template(
    env: object,
    obj: str | object
) -> str:
    """
    Get appropriate Jinja2 template for rendering objects.
    
    Parameters:
    - env: object - Jinja2 environment
    - obj: str | object - Object or template name
    
    Returns:
    str - Template name for the object
    """

def do_backlink_tree(
    backlinks: list
) -> Tree:
    """
    Create a tree structure of backlinks for navigation.
    
    Parameters:
    - backlinks: list - List of backlink objects
    
    Returns:
    Tree - Tree structure for navigation
    """

AutorefsHook Class

Hook class for automatic reference generation and integration with mkdocs-autorefs.

class AutorefsHook:
    """Hook class for automatic reference generation."""
    
    def __init__(
        self,
        current_object: object,
        config: dict[str, Any]
    ) -> None:
        """
        Initialize the AutorefsHook.
        
        Parameters:
        - current_object: object - Current object being processed
        - config: dict[str, Any] - Handler configuration
        """
        
    def expand_identifier(self, identifier: str) -> str:
        """
        Expand short identifiers to full dotted paths.
        
        Parameters:
        - identifier: str - Short identifier to expand
        
        Returns:
        str - Expanded dotted path
        """
        
    def get_context(self) -> object:
        """
        Get the current context for cross-reference resolution.
        
        Returns:
        object - Context object for autorefs
        """

Usage Example:

from mkdocstrings_handlers.python import AutorefsHook

# Create hook instance
hook = AutorefsHook()

# Use in mkdocstrings configuration
hook.on_config({"base_url": "https://example.com/docs/"})

Types

Order = Literal["__all__", "alphabetical", "source"]
"""
Ordering methods for organizing object members:
- __all__: Order according to __all__ module attribute
- alphabetical: Order alphabetically by name  
- source: Order by appearance in source code
"""

Tree = dict[str, Any]
"""Tree data structure for organizing hierarchical documentation."""

Install with Tessl CLI

npx tessl i tessl/pypi-mkdocstrings-python

docs

configuration.md

handler-core.md

index.md

rendering.md

tile.json