Note
Due to that for the documentation of mkdocstrings-matlab both the MATLAB and the Python handler are loaded, the symbols shown for Python objects will be incorrect (see Configuration).
matlab
¤
MATLAB handler for mkdocstrings.
Modules:
-
handler
–The mkdocstrings handler for processing MATLAB code documentation.
-
collect
–Functions and classes for collecting MATLAB objects from paths.
-
models
–Classes to represent MATLAB objects and their properties.
-
treesitter
–Tree-sitter queries to extract information from MATLAB files.
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(*args: Any, config_file_path: str | None = None, paths: list[str] | None = None, paths_recursive: bool = False, locale: str = 'en', **kwargs: Any)
The MatlabHandler
class is a handler for processing Matlab code documentation.
Parameters:
-
*args
¤Any
, default:()
) –Variable length argument list.
-
config_file_path
¤str | None
, default:None
) –Path to the configuration file. Defaults to None.
-
paths
¤list[str] | None
, default:None
) –List of paths to include. Defaults to None.
-
paths_recursive
¤bool
, default:False
) –Whether to include paths recursively. Defaults to False.
-
locale
¤str
, default:'en'
) –Locale setting. Defaults to "en".
-
**kwargs
¤Any
, default:{}
) –Arbitrary keyword arguments.
Returns:
-
None
–None
Methods:
-
collect
–Collect data given an identifier and user configuration.
-
render
–Render a template using provided data and configuration options.
-
update_env
–Update the Jinja environment with custom filters and tests.
Attributes:
-
default_config
(dict
) –Default handler configuration.
-
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_config
(dict
) –The configuration used to collect item during autorefs fallback.
-
fallback_theme
–The fallback theme.
-
name
(str
) –The handler's name.
default_config
class-attribute
¤
default_config: dict = {'show_bases': True, 'show_inheritance_diagram': False, 'show_source': True, 'heading_level': 2, 'parameter_headings': False, 'show_root_heading': False, 'show_root_toc_entry': True, 'show_root_full_path': True, 'show_root_members_full_path': False, 'show_object_full_path': False, 'show_category_heading': False, 'show_symbol_type_heading': False, 'show_symbol_type_toc': False, 'members': None, 'hidden_members': False, 'private_members': False, 'inherited_members': False, 'members_order': alphabetical.value, 'filters': ['!^delete$|^disp$'], 'group_by_category': True, 'show_subnamespaces': False, 'summary': False, 'show_labels': True, 'docstring_style': 'google', 'docstring_options': {}, 'docstring_section_style': 'table', 'parse_arguments': False, 'merge_constructor_into_class': False, 'merge_constructor_ignore_summary': False, 'show_if_no_docstring': False, 'show_docstring_propeties': True, 'show_docstring_functions': True, 'show_docstring_classes': True, 'show_docstring_namespaces': True, 'show_docstring_description': True, 'show_docstring_examples': True, 'show_docstring_input_arguments': True, 'show_docstring_name_value_arguments': True, 'show_docstring_output_arguments': True, 'show_signature': True, 'show_signature_annotations': False, 'separate_signature': False, 'signature_crossrefs': False}
Default handler configuration.
General options:
-
show_bases
(bool
) –Show the base classes of a class. Default:
True
. -
show_inheritance_diagram
(bool
) –Show the inheritance diagram of a class using Mermaid. Default:
False
. -
show_source
(bool
) –Show the source code of this object. Default:
True
.
Headings options:
-
heading_level
(int
) –The initial heading level to use. Default:
2
. -
parameter_headings
(bool
) –Whether to render headings for parameters (therefore showing parameters in the ToC). Default:
False
. -
show_root_heading
(bool
) –Show the heading of the object at the root of the documentation tree (i.e. the object referenced by the identifier after
:::
). Default:False
. -
show_root_toc_entry
(bool
) –If the root heading is not shown, at least add a ToC entry for it. Default:
True
. -
show_root_full_path
(bool
) –Show the full path for the root object heading. Default:
True
. -
show_root_members_full_path
(bool
) –Show the full path of the root members. Default:
False
. -
show_object_full_path
(bool
) –Show the full path of every object. Default:
False
. -
show_category_heading
(bool
) –When grouped by categories, show a heading for each category. Default:
False
. -
show_symbol_type_heading
(bool
) –Show the symbol type in headings (e.g. mod, class, meth, func and attr). Default:
False
. -
show_symbol_type_toc
(bool
) –Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr). Default:
False
.
Members options:
-
members
(list[str] | bool | None
) –A boolean, or an explicit list of members to render. If true, select all members without further filtering. If false or empty list, do not render members. If none, select all members and apply further filtering with filters and docstrings. Default:
None
. -
hidden_members
(list[str] | bool | None
) –A boolean, or an explicit list of hidden members to render. If true, select all inherited members, which can then be filtered with
members
. If false or empty list, do not select any hidden member. Default:False
. -
private_members
(list[str] | bool | None
) –A boolean, or an explicit list of private members to render. If true, select all inherited members, which can then be filtered with
members
. If false or empty list, do not select any private member. Default:False
. -
inherited_members
(list[str] | bool | None
) –A boolean, or an explicit list of inherited members to render. If true, select all inherited members, which can then be filtered with
members
. If false or empty list, do not select any inherited member. Default:False
. -
members_order
(str
) –The members ordering to use. Options:
alphabetical
- order by the members names,source
- order members as they appear in the source file. Default:"alphabetical"
. -
filters
(list[str] | None
) –A list of filters applied to filter objects based on their name. A filter starting with
!
will exclude matching objects instead of including them. Themembers
option takes precedence overfilters
(filters will still be applied recursively to lower members in the hierarchy). Default:["!^delete$|^disp$"]
. -
group_by_category
(bool
) –Group the object's children by categories: properties, classes, functions, and namespaces. Default:
True
. -
show_subnamespaces
(bool
) –When rendering a namespace, show its subnamespaces recursively. Default:
False
. -
summary
(bool | dict[str, bool]
) –Whether to render summaries of namespaces, classes, functions (methods) and properties. Default:
False
. -
show_labels
(bool
) –Whether to show labels of the members. Default:
True
.
Docstrings options:
-
docstring_style
(str
) –The docstring style to use:
google
,numpy
,sphinx
, orNone
. Default:"google"
. -
docstring_options
(dict
) –The options for the docstring parser. See docstring parsers and their options in Griffe docs.
-
docstring_section_style
(str
) –The style used to render docstring sections. Options:
table
,list
,spacy
. Default:"table"
. -
parse_arguments
(bool
) –Whether to load inputs and output parameters based on argument validation blocks. Default:
True
. -
merge_constructor_into_class
(bool
) –Whether to merge the constructor method into the class' signature and docstring. Default:
False
. -
merge_constructor_ignore_summary
(bool
) –Whether to ignore the constructor summary when merging it into the class. Default:
False
. -
show_if_no_docstring
(bool
) –Show the object heading even if it has no docstring or children with docstrings. Default:
False
. -
show_docstring_properties
(bool
) –Whether to display the "Properties" section in the object's docstring. Default:
True
. -
show_docstring_functions
(bool
) –Whether to display the "Functions" or "Methods" sections in the object's docstring. Default:
True
. -
show_docstring_classes
(bool
) –Whether to display the "Classes" section in the object's docstring. Default:
True
. -
show_docstring_namespaces
(bool
) –Whether to display the "Namespaces" section in the object's docstring. Default:
True
. -
show_docstring_description
(bool
) –Whether to display the textual block (including admonitions) in the object's docstring. Default:
True
. -
show_docstring_examples
(bool
) –Whether to display the "Examples" section in the object's docstring. Default:
True
. -
show_docstring_input_arguments
(bool
) –Whether to display the "Input arguments" section in the object's docstring. Default:
True
. -
show_docstring_name_value_arguments
(bool
) –Whether to display the "Name-value pairs" section in the object's docstring. Default:
True
. -
show_docstring_output_arguments
(bool
) –Whether to display the "Output arguments" section in the object's docstring. Default:
True
.
Signatures/annotations options:
-
show_signature
(bool
) –Show methods and functions signatures. Default:
True
. -
show_signature_annotations
(bool
) –Show the type annotations in methods and functions signatures. Default:
False
. -
separate_signature
(bool
) –Whether to put the whole signature in a code block below the heading.
-
signature_crossrefs
(bool
) –Whether to render cross-references for type annotations in signatures. Default:
False
.
domain
class-attribute
instance-attribute
¤
domain: str = 'mat'
The cross-documentation domain/language for this handler.
enable_inventory
class-attribute
instance-attribute
¤
enable_inventory: bool = True
Whether this handler is interested in enabling the creation of the objects.inv
Sphinx inventory file.
fallback_config
class-attribute
¤
fallback_config: dict = {'fallback': True}
The configuration used to collect item during autorefs fallback.
collect
¤
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.
-
config
¤Mapping[str, Any]
) –The handler's configuration options.
Returns:
-
CollectorItem
–CollectorItem
render
¤
get_handler
¤
get_handler(*, theme: str, custom_templates: str | None = None, config_file_path: str | None = None, paths: list[str] | None = None, paths_recursive: bool = False, **config: Any) -> MatlabHandler
Create and return a MatlabHandler object with the specified configuration.
Parameters:
-
theme
¤str
) –The theme to be used by the handler.
-
custom_templates
¤str | None
, default:None
) –Path to custom templates. Defaults to None.
-
config_file_path
¤str | None
, default:None
) –Path to the configuration file. Defaults to None.
-
paths
¤list[str] | None
, default:None
) –List of paths to include. Defaults to None.
-
paths_recursive
¤bool
, default:False
) –Whether to include paths recursively. Defaults to False.
-
**config
¤Any
, default:{}
) –Additional configuration options.
Returns:
-
MatlabHandler
(MatlabHandler
) –An instance of MatlabHandler configured with the provided parameters.
collect
¤
Functions and classes for collecting MATLAB objects from paths.
Classes:
-
LinesCollection
–A simple dictionary containing the modules source code lines.
-
PathCollection
–PathCollection is a class that manages a collection of MATLAB paths and their corresponding models.
LazyModel
¤
LazyModel(path: Path, path_collection: PathCollection)
A class to lazily collect and model MATLAB objects from a given path.
Methods:
-
is_class_folder
–Checks if the path is a class folder.
-
is_namespace
–Checks if the path is a namespace.
-
is_in_namespace
–Checks if the path is within a namespace.
-
name
–Returns the name of the MATLAB object, including namespace if applicable.
-
model
–Collects and returns the MATLAB object model..
PathCollection
¤
PathCollection is a class that manages a collection of MATLAB paths and their corresponding models.
Attributes:
-
config
(Mapping
) –Configuration settings for the PathCollection.
-
lines_collection
(LinesCollection
) –An instance of LinesCollection for managing lines.
Parameters:
-
matlab_path
¤Sequence[str | Path]
) –A list of strings or Path objects representing the MATLAB paths.
-
recursive
¤bool
, default:False
) –If True, recursively adds all subdirectories of the given paths to the search path. Defaults to False.
-
config
¤Mapping
, default:{}
) –Configuration settings for the PathCollection. Defaults to {}.
Methods:
-
members
–Returns a dictionary of members with their corresponding models.
-
resolve
–str, config: Mapping = {}) -> MatlabMixin | None: Resolves the given identifier to a model object.
-
update_model
–MatlabMixin, config: Mapping) -> MatlabMixin: Updates the given model object with the provided configuration.
-
addpath
–str | Path, to_end: bool = False, recursive: bool = False) -> list[Path]: Adds a path to the search path.
-
rm_path
–str | Path, recursive: bool = False) -> list[Path]: Removes a path from the search path and updates the namespace and database accordingly.
-
get_inheritance_diagram
–Class) -> DocstringSectionText | None: Generates an inheritance diagram for the given class model.
Parameters:
Raises:
-
TypeError
–If any element in matlab_path is not a string or Path object.
Methods:
-
addpath
–Add a path to the search path.
-
resolve
–Resolve an identifier to a MatlabMixin model.
-
rm_path
–Removes a path from the search path and updates the namespace and database accordingly.
-
update_model
–Update the given model based on the provided configuration.
addpath
¤
resolve
¤
resolve(identifier: str, config: Mapping = {})
Resolve an identifier to a MatlabMixin model.
This method attempts to resolve a given identifier to a corresponding MatlabMixin model using the internal mapping and models. If the identifier is not found directly, it will attempt to resolve it by breaking down the identifier into parts and resolving each part recursively.
Parameters:
-
identifier
¤str
) –The identifier to resolve.
-
config
¤Mapping
, default:{}
) –Configuration options to update the model. Defaults to an empty dictionary.
Returns:
-
–
MatlabMixin or None: The resolved MatlabMixin model if found, otherwise None.
rm_path
¤
Removes a path from the search path and updates the namespace and database accordingly.
Parameters:
-
path
¤str | Path
) –The path to be removed from the search path.
-
recursive
¤bool
, default:False
) –If True, recursively removes all subdirectories of the given path from the search path. Defaults to False.
Returns:
-
–
list[Path]: The previous search path before the removal.
update_model
¤
Update the given model based on the provided configuration.
This method updates the docstring parser and parser options for the model, patches return annotations for MATLAB functions, and optionally creates docstring sections from argument blocks. It also recursively updates members of the model and handles special cases for class constructors and inheritance diagrams.
Parameters:
Returns:
-
MatlabMixin
(MatlabMixin
) –The updated model.
models
¤
Classes to represent MATLAB objects and their properties.
Classes:
-
Class
–Represents a MATLAB class with additional properties and methods for handling
-
Classfolder
–A class representing a MATLAB classfolder
-
Docstring
–A class to represent a docstring with additional sections.
-
Function
–Represents a MATLAB function with various attributes and properties.
-
MatlabObject
–Represents a Matlab object with associated docstring, path collection, and parent object.
-
Namespace
–A class representing a namespace in a MATLAB project.
-
Parameter
–Represents a parameter in a MATLAB object.
-
Parameters
–A class to represent a collection of parameters.
-
Script
–A class representing a MATLAB script.
Class
¤
Class(*args: Any, Abstract: bool = False, Hidden: bool = False, Sealed: bool = False, **kwargs: Any)
Represents a MATLAB class with additional properties and methods for handling MATLAB-specific features.
This class extends PathMixin
, MatlabObject
, and GriffeClass
to provide
additional functionality for handling MATLAB class properties such as
abstract, hidden, and sealed attributes. It also provides methods to retrieve
parameters, inherited members, and labels.
Attributes:
-
abstract
(bool
) –Indicates if the class is abstract.
-
hidden
(bool
) –Indicates if the class is hidden.
-
sealed
(bool
) –Indicates if the class is sealed.
Parameters:
-
*args
¤Any
, default:()
) –Variable length argument list.
-
Abstract
¤bool
, default:False
) –Indicates if the class is abstract
-
Hidden
¤bool
, default:False
) –Indicates if the class is hidden
-
Sealed
¤bool
, default:False
) –Indicates if the class is sealed
Attributes:
-
inherited_members
(dict[str, MatlabObject]
) –Retrieve a dictionary of inherited members from base classes.
-
parameters
(Parameters
) –Retrieve the parameters of the class by grabbing its constructor.
inherited_members
property
¤
inherited_members: dict[str, MatlabObject]
Retrieve a dictionary of inherited members from base classes.
This method iterates over the base classes in reverse order, resolves their models, and collects members that are not already present in the current object's members.
Returns:
-
dict[str, MatlabObject]
–dict[str, MatlabObject]: A dictionary where the keys are member names and the values are the corresponding MatlabObject instances.
parameters
property
¤
parameters: Parameters
Retrieve the parameters of the class by grabbing its constructor.
Returns:
-
Parameters
(Parameters
) –The parameters of the function if the current member is a function, otherwise an empty Parameters object.
Classfolder
¤
Classfolder(*args: Any, Abstract: bool = False, Hidden: bool = False, Sealed: bool = False, **kwargs: Any)
A class representing a MATLAB classfolder
Attributes:
-
inherited_members
(dict[str, MatlabObject]
) –Retrieve a dictionary of inherited members from base classes.
-
parameters
(Parameters
) –Retrieve the parameters of the class by grabbing its constructor.
inherited_members
property
¤
inherited_members: dict[str, MatlabObject]
Retrieve a dictionary of inherited members from base classes.
This method iterates over the base classes in reverse order, resolves their models, and collects members that are not already present in the current object's members.
Returns:
-
dict[str, MatlabObject]
–dict[str, MatlabObject]: A dictionary where the keys are member names and the values are the corresponding MatlabObject instances.
parameters
property
¤
parameters: Parameters
Retrieve the parameters of the class by grabbing its constructor.
Returns:
-
Parameters
(Parameters
) –The parameters of the function if the current member is a function, otherwise an empty Parameters object.
Docstring
¤
A class to represent a docstring with additional sections.
This class extends the GriffeDocstring class to include extra sections that can be added to the parsed docstring.
Attributes:
-
_suffixes
(list[DocstringSection]
) –A list to store additional docstring sections.
Methods:
-
parsed
–Returns the parsed docstring sections combined with extra sections.
-
_parsed
–Parses the docstring into structured data.
Parameters:
-
*args
¤Any
, default:()
) –Variable length argument list.
-
**kwargs
¤Any
, default:{}
) –Arbitrary keyword arguments.
Attributes:
Function
¤
Function(*args: Any, returns: Parameters | None = None, Abstract: bool = False, Access: AccessEnum = public, Hidden: bool = False, Sealed: bool = False, Static: bool = False, setter: bool = False, getter: bool = False, **kwargs: Any)
Represents a MATLAB function with various attributes and properties.
Attributes:
-
parameters
(Parameters
) –The parameters of the function.
-
returns
(Parameters | None
) –The return parameters of the function.
-
access
(AccessEnum
) –The access level of the function.
-
static
(bool
) –Indicates if the function is static.
-
abstract
(bool
) –Indicates if the function is abstract.
-
sealed
(bool
) –Indicates if the function is sealed.
-
hidden
(bool
) –Indicates if the function is hidden.
-
_is_setter
(bool
) –Indicates if the function is a setter.
-
_is_getter
(bool
) –Indicates if the function is a getter.
Parameters:
-
*args
¤Any
, default:()
) –Variable length argument list.
-
returns
¤Parameters | None
, default:None
) –The return parameters of the function. Defaults to None.
-
Abstract
¤bool
, default:False
) –Indicates if the function is abstract. Defaults to False.
-
Access
¤AccessEnum
, default:public
) –The access level of the function. Defaults to AccessEnum.public.
-
Hidden
¤bool
, default:False
) –Indicates if the function is hidden. Defaults to False.
-
Sealed
¤bool
, default:False
) –Indicates if the function is sealed. Defaults to False.
-
Static
¤bool
, default:False
) –Indicates if the function is static. Defaults to False.
-
setter
¤bool
, default:False
) –Indicates if the function is a setter. Defaults to False.
-
getter
¤bool
, default:False
) –Indicates if the function is a getter. Defaults to False.
Attributes:
-
canonical_path
(str
) –The full dotted path of this object.
MatlabObject
¤
MatlabObject(*args, path_collection: PathCollection | None = None, **kwargs)
Represents a Matlab object with associated docstring, path collection, and parent object.
Attributes:
-
path_collection
(PathCollection | None
) –The collection of paths related to the Matlab object.
Parameters:
-
*args
¤Variable length argument list.
-
path_collection
¤PathCollection | None
, default:None
) –The collection of paths related to the object.
-
**kwargs
¤Arbitrary keyword arguments.
Attributes:
-
canonical_path
(str
) –The full dotted path of this object.
Namespace
¤
A class representing a namespace in a MATLAB project.
Inherits from
- PathMixin: A mixin class providing path-related functionality.
- MatlabObject: A base class for MATLAB objects.
- Module: A class representing a module.
Attributes:
-
canonical_path
(str
) –The full dotted path of this object.
Parameter
¤
Represents a parameter in a MATLAB object.
Inherits from
MatlabObject: Base class for MATLAB objects. GriffeParameter: Base class for parameters.
Attributes:
-
kind
(ParameterKind | None
) –The kind of the parameter, which can be of type ParameterKind or None.
Attributes:
-
canonical_path
(str
) –The full dotted path of this object.
Parameters
¤
A class to represent a collection of parameters.
Inherits from
MatlabObject: Base class for MATLAB objects. GriffeParameters: Base class for handling parameters.
Attributes:
-
canonical_path
(str
) –The full dotted path of this object.
PathMixin
¤
A mixin class that provides a filepath attribute and related functionality.
Attributes:
-
filepath
(Path | None
) –The file path associated with the object. It can be None if no file path is provided.
Script
¤
Script(*args: Any, parent: Class | Classfolder | Namespace | _Root | None = None, docstring: Docstring | None = None, **kwargs: Any)
A class representing a MATLAB script.
This class inherits from PathMixin
and MatlabObject
to provide
functionality specific to MATLAB scripts.
Attributes:
-
canonical_path
(str
) –The full dotted path of this object.
treesitter
¤
Tree-sitter queries to extract information from MATLAB files.
Classes:
-
FileParser
–A class to parse MATLAB files using Tree-sitter.
FileParser
¤
A class to parse MATLAB files using Tree-sitter.
Attributes:
-
filepath
(Path
) –The path to the MATLAB file.
-
encoding
(str
) –The encoding of the file content.
-
content
–Returns the decoded content of the file.
Methods:
-
parse
–Parses the MATLAB file and returns a MatlabMixin.
Parameters:
Methods:
-
parse
–Parse the content of the file and return a MatlabMixin.
Attributes:
-
content
–Property that decodes and returns the content using the specified encoding.
content
property
¤
content
Property that decodes and returns the content using the specified encoding.
Returns:
-
str
–The decoded content.
parse
¤
parse(**kwargs) -> MatlabMixin
Parse the content of the file and return a MatlabMixin.
This method uses a tree-sitter parser to parse the content of the file and extract relevant information to create a MatlabMixin. It handles different types of Matlab constructs such as functions and classes.
Parameters:
-
**kwargs
¤Additional keyword arguments to pass to the parsing methods.
Returns:
-
MatlabMixin
(MatlabMixin
) –An instance of MatlabMixin representing the parsed content.
Raises:
-
ValueError
–If the file could not be parsed.