Skip to content

matlab ¤

MATLAB handler for mkdocstrings.

Modules:

  • handler –

    The mkdocstrings handler for processing MATLAB code documentation.

  • config –

    Configuration and options dataclasses.

handler ¤

The mkdocstrings handler for processing MATLAB code documentation.

Classes:

  • MatlabHandler –

    The MatlabHandler class is a handler for processing Matlab code documentation.

Functions:

  • get_handler –

    Create and return a MatlabHandler object with the specified configuration.

MatlabHandler ¤

MatlabHandler(
    config: MatlabConfig, base_dir: Path, **kwargs: Any
)

The MatlabHandler class is a handler for processing Matlab code documentation.

Parameters:

  • config ¤

    (MatlabConfig) –

    The handler configuration.

  • base_dir ¤

    (Path) –

    The base directory of the project.

  • **kwargs ¤

    (Any, default: {} ) –

    Arguments passed to the parent constructor.

Returns:

  • None –

    None

Methods:

  • collect –

    Collect data given an identifier and user configuration.

  • get_options –

    Get combined default, global and local options.

  • render –

    Render a template using provided data and configuration options.

  • update_env –

    Update the Jinja environment with custom filters and tests.

Attributes:

  • domain (str) –

    The cross-documentation domain/language for this handler.

  • enable_inventory (bool) –

    Whether this handler is interested in enabling the creation of the objects.inv Sphinx inventory file.

  • fallback_theme (str) –

    The fallback theme.

  • name (str) –

    The MATLAB handler class.

domain class-attribute ¤

domain: str = 'mat'

The cross-documentation domain/language for this handler.

enable_inventory class-attribute ¤

enable_inventory: bool = True

Whether this handler is interested in enabling the creation of the objects.inv Sphinx inventory file.

fallback_theme class-attribute ¤

fallback_theme: str = 'material'

The fallback theme.

name class-attribute ¤

name: str = 'matlab'

The MATLAB handler class.

collect ¤

collect(
    identifier: str, options: MatlabOptions
) -> CollectorItem

Collect data given an identifier and user configuration.

In the implementation, you typically call a subprocess that returns JSON, and load that JSON again into a Python dictionary for example, though the implementation is completely free.

Parameters:

  • identifier ¤
    (str) –

    An identifier for which to collect data.

  • options ¤
    (MatlabOptions) –

    The handler's configuration options.

Returns:

  • CollectorItem –

    CollectorItem

get_options ¤

get_options(
    local_options: Mapping[str, Any],
) -> HandlerOptions

Get combined default, global and local options.

Parameters:

Returns:

  • HandlerOptions –

    The combined options.

render ¤

render(data: CollectorItem, options: MatlabOptions) -> str

Render a template using provided data and configuration options.

Parameters:

  • data ¤
    (CollectorItem) –

    The collected data to render.

  • options ¤
    (MatlabOptions) –

    The handler's configuration options.

Returns:

  • str –

    The rendered template as HTML.

update_env ¤

update_env(config: Any) -> None

Update the Jinja environment with custom filters and tests.

Parameters:

  • config ¤
    (Any) –

    The SSG configuration.

get_handler ¤

get_handler(
    handler_config: MutableMapping[str, Any],
    tool_config: MkDocsConfig,
    **kwargs: Any,
) -> MatlabHandler

Create and return a MatlabHandler object with the specified configuration.

Parameters:

tool_config: The tool (SSG) configuration.

Returns:

  • MatlabHandler ( MatlabHandler ) –

    An instance of MatlabHandler configured with the provided parameters.

config ¤

Configuration and options dataclasses.

Classes:

AutoStyleOptions dataclass ¤

AutoStyleOptions(
    *,
    method: Literal[
        "heuristics", "max_sections"
    ] = "heuristics",
    style_order: list[str] = lambda: [
        "sphinx",
        "google",
        "numpy",
    ](),
    default: str | None = None,
    per_style_options: PerStyleOptions = PerStyleOptions(),
)

Auto style docstring options.

Methods:

  • from_data –

    Create an instance from a dictionary.

from_data classmethod ¤

from_data(**data: Any) -> Self

Create an instance from a dictionary.

GoogleStyleOptions dataclass ¤

GoogleStyleOptions(
    *,
    ignore_init_summary: bool = False,
    returns_multiple_items: bool = True,
    returns_named_value: bool = True,
    returns_type_in_property_summary: bool = False,
    receives_multiple_items: bool = True,
    receives_named_value: bool = True,
    trim_doctest_flags: bool = True,
    warn_unknown_params: bool = True,
)

Google style docstring options.

Inventory dataclass ¤

Inventory(
    *,
    url: str,
    base: str | None = None,
    domains: list[str] = lambda: ["py"](),
)

An inventory.

MatlabConfig dataclass ¤

MatlabConfig(
    *,
    inventories: list[Inventory] = list(),
    paths: list[str] = lambda: ["."](),
    paths_recursive: bool = False,
    options: dict[str, Any] = dict(),
    locale: str | None = None,
)

MATLAB handler configuration.

Methods:

  • coerce –

    Coerce data.

  • from_data –

    Create an instance from a dictionary.

coerce classmethod ¤

coerce(**data: Any) -> MutableMapping[str, Any]

Coerce data.

from_data classmethod ¤

from_data(**data: Any) -> Self

Create an instance from a dictionary.

MatlabInputConfig dataclass ¤

MatlabInputConfig(
    *,
    inventories: list[str | Inventory] = list(),
    paths: list[str] = lambda: ["."](),
    paths_recursive: bool = False,
    options: MatlabInputOptions = MatlabInputOptions(),
    locale: str | None = None,
)

MATLAB handler configuration.

Methods:

  • coerce –

    Coerce data.

  • from_data –

    Create an instance from a dictionary.

coerce classmethod ¤

coerce(**data: Any) -> MutableMapping[str, Any]

Coerce data.

from_data classmethod ¤

from_data(**data: Any) -> Self

Create an instance from a dictionary.

MatlabInputOptions dataclass ¤

MatlabInputOptions(
    *,
    docstring_options: GoogleStyleOptions
    | NumpyStyleOptions
    | SphinxStyleOptions
    | AutoStyleOptions
    | None = None,
    docstring_section_style: Literal[
        "table", "list", "spacy"
    ] = "table",
    docstring_style: Literal[
        "auto", "google", "numpy", "sphinx"
    ]
    | None = "google",
    parse_arguments: bool = True,
    filters: list[str] = lambda: ["!^delete$|^disp$"](),
    group_by_category: bool = True,
    heading: str = "",
    heading_level: int = 2,
    hidden_members: bool | list[str] = False,
    private_members: bool | list[str] = False,
    inherited_members: bool | list[str] = False,
    line_length: int = 60,
    members: list[str] | bool | None = None,
    members_order: Literal[
        "alphabetical", "source"
    ] = "alphabetical",
    merge_constructor_into_class: bool = False,
    argument_headings: bool = False,
    separate_signature: bool = False,
    show_bases: bool = True,
    show_category_heading: bool = False,
    show_docstring_classes: bool = True,
    show_docstring_description: bool = True,
    show_docstring_examples: bool = True,
    show_docstring_functions: bool = True,
    show_docstring_namespaces: bool = True,
    show_docstring_properties: bool = True,
    show_docstring_input_arguments: bool = True,
    show_docstring_name_value_arguments: bool = True,
    show_docstring_output_arguments: bool = True,
    show_if_no_docstring: bool = False,
    show_inheritance_diagram: bool = False,
    show_attributes: bool = True,
    show_object_full_path: bool = False,
    show_root_full_path: bool = True,
    show_root_heading: bool = False,
    show_root_members_full_path: bool = False,
    show_root_toc_entry: bool = True,
    show_signature_types: bool = False,
    show_signature: bool = True,
    show_source: bool = True,
    show_subnamespaces: bool = False,
    show_symbol_type_heading: bool = False,
    show_symbol_type_toc: bool = False,
    signature_crossrefs: bool = False,
    summary: bool | SummaryOption = SummaryOption(),
    toc_label: str = "",
    extra: dict[str, Any] = dict(),
)

Accepted input options.

Methods:

  • coerce –

    Coerce data.

  • from_data –

    Create an instance from a dictionary.

coerce classmethod ¤

coerce(**data: Any) -> MutableMapping[str, Any]

Coerce data.

from_data classmethod ¤

from_data(**data: Any) -> Self

Create an instance from a dictionary.

MatlabOptions dataclass ¤

MatlabOptions(
    *,
    docstring_options: GoogleStyleOptions
    | NumpyStyleOptions
    | SphinxStyleOptions
    | AutoStyleOptions
    | None = None,
    docstring_section_style: Literal[
        "table", "list", "spacy"
    ] = "table",
    docstring_style: Literal[
        "auto", "google", "numpy", "sphinx"
    ]
    | None = "google",
    parse_arguments: bool = True,
    filters: list[tuple[Pattern, bool]] = list(),
    group_by_category: bool = True,
    heading: str = "",
    heading_level: int = 2,
    hidden_members: bool | list[str] = False,
    private_members: bool | list[str] = False,
    inherited_members: bool | list[str] = False,
    line_length: int = 60,
    members: list[str] | bool | None = None,
    members_order: Literal[
        "alphabetical", "source"
    ] = "alphabetical",
    merge_constructor_into_class: bool = False,
    argument_headings: bool = False,
    separate_signature: bool = False,
    show_bases: bool = True,
    show_category_heading: bool = False,
    show_docstring_classes: bool = True,
    show_docstring_description: bool = True,
    show_docstring_examples: bool = True,
    show_docstring_functions: bool = True,
    show_docstring_namespaces: bool = True,
    show_docstring_properties: bool = True,
    show_docstring_input_arguments: bool = True,
    show_docstring_name_value_arguments: bool = True,
    show_docstring_output_arguments: bool = True,
    show_if_no_docstring: bool = False,
    show_inheritance_diagram: bool = False,
    show_attributes: bool = True,
    show_object_full_path: bool = False,
    show_root_full_path: bool = True,
    show_root_heading: bool = False,
    show_root_members_full_path: bool = False,
    show_root_toc_entry: bool = True,
    show_signature_types: bool = False,
    show_signature: bool = True,
    show_source: bool = True,
    show_subnamespaces: bool = False,
    show_symbol_type_heading: bool = False,
    show_symbol_type_toc: bool = False,
    signature_crossrefs: bool = False,
    summary: SummaryOption = SummaryOption(),
    toc_label: str = "",
    extra: dict[str, Any] = dict(),
)

Final options passed as template context.

Methods:

  • coerce –

    Create an instance from a dictionary.

  • from_data –

    Create an instance from a dictionary.

Attributes:

filters class-attribute instance-attribute ¤

filters: list[tuple[Pattern, bool]] = field(
    default_factory=list
)

A list of filters applied to filter objects based on their name.

summary class-attribute instance-attribute ¤

summary: SummaryOption = field(
    default_factory=SummaryOption
)

Whether to render summaries of namespaces, classes, functions (methods) and properties.

coerce classmethod ¤

coerce(**data: Any) -> MutableMapping[str, Any]

Create an instance from a dictionary.

from_data classmethod ¤

from_data(**data: Any) -> Self

Create an instance from a dictionary.

NumpyStyleOptions dataclass ¤

NumpyStyleOptions(
    *,
    ignore_init_summary: bool = False,
    trim_doctest_flags: bool = True,
    warn_unknown_params: bool = True,
)

Numpy style docstring options.

PerStyleOptions dataclass ¤

PerStyleOptions(
    *,
    google: GoogleStyleOptions = GoogleStyleOptions(),
    numpy: NumpyStyleOptions = NumpyStyleOptions(),
    sphinx: SphinxStyleOptions = SphinxStyleOptions(),
)

Per style options.

Methods:

  • from_data –

    Create an instance from a dictionary.

from_data classmethod ¤

from_data(**data: Any) -> Self

Create an instance from a dictionary.

SphinxStyleOptions dataclass ¤

SphinxStyleOptions()

Sphinx style docstring options.

SummaryOption dataclass ¤

SummaryOption(
    *,
    properties: bool = False,
    functions: bool = False,
    classes: bool = False,
    namespaces: bool = False,
)

Summary option.