mkdocstrings-matlab 0.1.0__py2.py3-none-any.whl

mkdocstrings_handlers/matlab/__init__.py

@@ -0,0 +1,5 @@
+"""MATLAB handler for mkdocstrings."""
+
+from mkdocstrings_handlers.matlab.handler import get_handler
+
+__all__ = ["get_handler"]

mkdocstrings_handlers/matlab/handler.py

@@ -0,0 +1,383 @@
+from pathlib import Path
+from collections import ChainMap
+from markdown import Markdown
+from mkdocstrings.handlers.base import BaseHandler, CollectorItem, CollectionError
+from mkdocstrings_handlers.python import rendering
+from typing import Any, ClassVar, Mapping
+from griffe import Docstring, Parameters, Parameter, ParameterKind
+from pprint import pprint
+
+
+import json
+
+
+from mkdocstrings_handlers.matlab_engine import MatlabEngine, MatlabExecutionError
+from mkdocstrings_handlers.matlab.models import Function, Class, Classfolder, Namespace, Property
+
+
+ROOT_NAMESPACE = Namespace("", filepath="")
+MODELS = {}
+
+
+class MatlabHandler(BaseHandler):
+    """The `MatlabHandler` class is a handler for processing Matlab code documentation.
+
+    Attributes:
+        name (str): The handler's name.
+        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.
+        fallback_config (ClassVar[dict]): The configuration used to collect item during autorefs fallback.
+        default_config (ClassVar[dict]): The default configuration for the handler.
+
+    Methods:
+        __init__(self, *args, config_file_path=None, paths=None, startup_expression="", locale="en", **kwargs): Initializes a new instance of the `MatlabHandler` class.
+        get_templates_dir(self, handler=None): Returns the templates directory for the handler.
+        collect(self, identifier, config): Collects the documentation for the given identifier.
+        render(self, data, config): Renders the collected documentation data.
+        update_env(self, md, config): Updates the Jinja environment with custom filters and tests.
+    """
+
+    name: str = "matlab"
+    """The handler's name."""
+    domain: str = "mat"  # to match Sphinx's default domain
+    """The cross-documentation domain/language for this handler."""
+    enable_inventory: bool = True
+    """Whether this handler is interested in enabling the creation of the `objects.inv` Sphinx inventory file."""
+    fallback_theme = "material"
+    """The fallback theme."""
+    fallback_config: ClassVar[dict] = {"fallback": True}
+    """The configuration used to collect item during autorefs fallback."""
+    default_config: ClassVar[dict] = {
+        # https://mkdocstrings.github.io/python/usage/
+        # General options
+        # "find_stubs_package": False,
+        # "allow_inspection": True,
+        "show_bases": True,
+        "show_inheritance_diagram": False,  # not implemented
+        "show_source": False,  # not implemented
+        # "preload_modules": None,
+        # Heading options
+        "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,
+        # Member options
+        "inherited_members": False,
+        "members": None,
+        "members_order": rendering.Order.alphabetical.value,
+        "filters": ["!^_[^_]"],
+        "group_by_category": True,
+        "show_submodules": False,
+        "summary": False,
+        "show_labels": True,
+        # Docstring options
+        "docstring_style": "google",
+        "docstring_options": {},
+        "docstring_section_style": "table",
+        "merge_init_into_class": False,
+        "show_if_no_docstring": False,
+        "show_docstring_attributes": True,
+        "show_docstring_functions": True,
+        "show_docstring_classes": True,
+        "show_docstring_modules": True,
+        "show_docstring_description": True,
+        "show_docstring_examples": True,
+        "show_docstring_other_parameters": True,
+        "show_docstring_parameters": True,
+        "show_docstring_raises": True,
+        "show_docstring_receives": True,
+        "show_docstring_returns": True,
+        "show_docstring_warns": True,
+        "show_docstring_yields": True,
+        # Signature options
+        "annotations_path": "brief",
+        "line_length": 60,
+        "show_signature": True,
+        "show_signature_annotations": False,
+        "signature_crossrefs": False,
+        "separate_signature": True,
+        "unwrap_annotated": False,
+        "modernize_annotations": False,
+    }
+
+    def __init__(
+        self,
+        *args: Any,
+        config_file_path: str | None = None,
+        paths: list[str] | None = None,
+        startup_expression: str = "",
+        locale: str = "en",
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+
+        if paths is None:
+            paths = ""
+
+        self.engine = MatlabEngine()
+        self.engine.addpath(str(Path(__file__).parent / "matlab"))
+        self.engine.matlab_startup(paths, startup_expression)
+        self._locale = locale
+
+    def get_templates_dir(self, handler: str | None = None) -> Path:
+        # use the python handler templates
+        # (it assumes the python handler is installed)
+        return super().get_templates_dir("python")
+
+    def collect(self, identifier: str, config: Mapping[str, Any]) -> 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.
+
+        Arguments:
+            identifier: An identifier for which to collect data.
+            config: The handler's configuration options.
+
+        Returns:
+            CollectorItem
+        """
+        final_config = ChainMap(config, self.default_config)  # type: ignore[arg-type]
+        try:
+            ast_json = self.engine.docstring.resolve(identifier)
+        except MatlabExecutionError as error:
+            raise CollectionError(error.args[0].strip()) from error
+        ast_dict = json.loads(ast_json)
+
+        match ast_dict["type"]:
+            case "function":
+                return collect_function(ast_dict, final_config)
+            case "method":
+                return collect_function(ast_dict, final_config)
+            case "class":
+                return self.collect_class(ast_dict, final_config)
+            case _:
+                return None
+
+    def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str:
+        """Render a template using provided data and configuration options.
+
+        Arguments:
+            data: The collected data to render.
+            config: The handler's configuration options.
+
+        Returns:
+            The rendered template as HTML.
+        """
+        final_config = ChainMap(config, self.default_config)  # type: ignore[arg-type]
+
+        template_name = rendering.do_get_template(self.env, data)
+        template = self.env.get_template(template_name)
+
+        heading_level = final_config["heading_level"]
+
+        return template.render(
+            **{
+                "config": final_config,
+                data.kind.value: data,
+                "heading_level": heading_level,
+                "root": True,
+                "locale": self._locale,
+            },
+        )
+
+    def get_anchors(self, data: CollectorItem) -> tuple[str, ...]:
+        """Return the possible identifiers (HTML anchors) for a collected item.
+
+        Arguments:
+            data: The collected data.
+
+        Returns:
+            The HTML anchors (without '#'), or an empty tuple if this item doesn't have an anchor.
+        """
+        anchors = [data.path]
+        return tuple(anchors)
+
+    def update_env(self, md: Markdown, config: dict) -> None:
+        """Update the Jinja environment with custom filters and tests.
+
+        Parameters:
+            md: The Markdown instance.
+            config: The configuration dictionary.
+        """
+        super().update_env(md, config)
+        self.env.trim_blocks = True
+        self.env.lstrip_blocks = True
+        self.env.keep_trailing_newline = False
+        self.env.filters["split_path"] = rendering.do_split_path
+        self.env.filters["crossref"] = rendering.do_crossref
+        self.env.filters["multi_crossref"] = rendering.do_multi_crossref
+        self.env.filters["order_members"] = rendering.do_order_members
+        self.env.filters["format_code"] = rendering.do_format_code
+        self.env.filters["format_signature"] = rendering.do_format_signature
+        self.env.filters["format_attribute"] = rendering.do_format_attribute
+        self.env.filters["filter_objects"] = rendering.do_filter_objects
+        self.env.filters["stash_crossref"] = lambda ref, length: ref
+        self.env.filters["get_template"] = rendering.do_get_template
+        self.env.filters["as_attributes_section"] = rendering.do_as_attributes_section
+        self.env.filters["as_functions_section"] = rendering.do_as_functions_section
+        self.env.filters["as_classes_section"] = rendering.do_as_classes_section
+        self.env.filters["as_modules_section"] = rendering.do_as_modules_section
+        self.env.tests["existing_template"] = (
+            lambda template_name: template_name in self.env.list_templates()
+        )
+
+
+    def collect_class(self, ast_dict: dict, config: Mapping) -> Class:
+        docstring = (
+            Docstring(ast_dict["docstring"], parser=config["docstring_style"])
+            if ast_dict["docstring"]
+            else None
+        )
+        object = Class(
+            ast_dict["name"],
+            docstring=docstring,
+            parent=get_parent(Path(ast_dict["path"]).parent),
+            hidden=ast_dict["hidden"],
+            sealed=ast_dict["sealed"],
+            abstract=ast_dict["abstract"],
+            enumeration=ast_dict["enumeration"],
+            handle=ast_dict["handle"],
+        )
+
+
+        for property_dict in ast_dict["properties"]:
+            name = property_dict.pop("name")
+            defining_class = property_dict.pop("class")
+            property_doc = property_dict.pop("docstring")
+            docstring = (
+                Docstring(property_doc, parser=config["docstring_style"])
+                if property_doc
+                else None
+            )
+            if defining_class != object.canonical_path and not config["inherited_members"]:
+                continue
+
+            object.members[name] = Property(name, docstring=docstring, **property_dict)
+
+        for method_dict in ast_dict["methods"]:
+            name = method_dict.pop("name")
+            defining_class = method_dict.pop("class")
+            if defining_class != object.canonical_path and not config["inherited_members"]:
+                continue
+            
+            method = self.collect(f"{defining_class}.{name}", config)
+            method._access = method_dict["access"]
+            method._static = method_dict["static"]
+            method._abstract = method_dict["abstract"]
+            method._sealed = method_dict["sealed"]
+            method._hidden = method_dict["hidden"]
+
+            object.members[name] = method
+
+        return object
+
+def get_parent(path: Path) -> Namespace | Classfolder:
+    if path.stem[0] == "+":
+        if path in MODELS:
+            parent = MODELS[path]
+        else:
+            parent = Namespace(
+                path.stem[1:], filepath=str(path), parent=get_parent(path.parent)
+            )
+            MODELS[path] = parent
+    elif path.stem[0] == "@":
+        if path in MODELS:
+            parent = MODELS[path]
+        else:
+            parent = Classfolder(
+                path.stem[1:], filepath=str(path), parent=get_parent(path.parent)
+            )
+            MODELS[path] = parent
+    else:
+        parent = ROOT_NAMESPACE
+    return parent
+
+
+
+
+
+def collect_function(ast_dict: dict, config: Mapping) -> Function:
+    parameters = []
+
+    inputs = (
+        ast_dict["inputs"]
+        if isinstance(ast_dict["inputs"], list)
+        else [ast_dict["inputs"]]
+    )
+    for input_dict in inputs:
+        if input_dict["name"] == "varargin":
+            parameter_kind = ParameterKind.var_positional
+        elif input_dict["kind"] == "positional":
+            parameter_kind = ParameterKind.positional_only
+        else:
+            parameter_kind = ParameterKind.keyword_only
+
+        parameters.append(
+            Parameter(
+                input_dict["name"],
+                kind=parameter_kind,
+                annotation=input_dict["class"],
+                default=input_dict["default"] if input_dict["default"] else None,
+            )
+        )
+
+    func = Function(
+        ast_dict["name"],
+        parameters=Parameters(*parameters),
+        docstring=Docstring(
+            ast_dict["docstring"],
+            parser=config["docstring_style"],
+            parser_options=config["docstring_options"],
+        )
+        if ast_dict["docstring"]
+        else None,
+        parent=get_parent(Path(ast_dict["path"]).parent),
+    )
+
+    return func
+
+
+def get_handler(
+    *,
+    theme: str,
+    custom_templates: str | None = None,
+    config_file_path: str | None = None,
+    paths: list[str] | None = None,
+    startup_expression: str = "",
+    **config: Any,
+) -> MatlabHandler:
+    """
+    Returns a MatlabHandler object.
+
+    Parameters:
+        theme (str): The theme to use.
+        custom_templates (str | None, optional): Path to custom templates. Defaults to None.
+        config_file_path (str | None, optional): Path to configuration file. Defaults to None.
+        paths (list[str] | None, optional): List of paths to include. Defaults to None.
+        startup_expression (str, optional): Startup expression. Defaults to "".
+        **config (Any): Additional configuration options.
+
+    Returns:
+        MatlabHandler: The created MatlabHandler object.
+    """
+    return MatlabHandler(
+        handler="matlab",
+        theme=theme,
+        custom_templates=custom_templates,
+        config_file_path=config_file_path,
+        paths=paths,
+        startup_expression=startup_expression,
+    )
+
+
+if __name__ == "__main__":
+    handler = get_handler(theme="material")
+    pprint(handler.collect("matlab_startup", {}).docstring.parse("google"))

mkdocstrings_handlers/matlab/matlab/+docstring/+case/builtin.m

@@ -0,0 +1,8 @@
+function data = builtin(identifier)
+    data.name = identifier;
+    data.type = 'function';
+    data.doc = help(identifier);
+    data.location = string(which(identifier));
+    data.inputs = struct.empty();
+    data.outputs = struct.empty();
+end

mkdocstrings_handlers/matlab/matlab/+docstring/+case/class.m

@@ -0,0 +1,12 @@
+function data = class(identifier)
+
+    if isMATLABReleaseOlderThan('R2024a')
+        metaclass = @meta.class.fromName;
+    else
+        metaclass = @matlab.metadata.Class.fromName;
+    end
+
+    object = metaclass(identifier);
+    data = docstring.metadata.class(object);
+
+end

mkdocstrings_handlers/matlab/matlab/+docstring/+case/func.m

@@ -0,0 +1,5 @@
+function data = func(identifier)
+
+    object = matlab.internal.metafunction(identifier);
+    data = docstring.metadata.func(object);
+end

mkdocstrings_handlers/matlab/matlab/+docstring/+case/method.m

@@ -0,0 +1,6 @@
+function data = method(identifier)
+
+    object = matlab.internal.metafunction(identifier);
+    data = docstring.metadata.func(object);
+    data.type = 'method';
+end

mkdocstrings_handlers/matlab/matlab/+docstring/+case/namespace.m

@@ -0,0 +1,28 @@
+function data = namespace(identifier)
+
+    currentpath = split(pwd, filesep);
+
+    name = identifier(2:end);
+    
+    if isfolder(identifier)
+        for i = numel(currentpath):-1:1
+            directory = currentpath(i);
+            if isempty(directory)
+                break
+            elseif strcmp(directory(1), '+')
+                name = sprintf("%s.%s", directory(2:end), name);
+            else
+                break
+            end
+        end
+    end
+
+    object = matlab.metadata.Namespace.fromName(name);
+
+    if isempty(object)
+        docstring.exception(identifier)
+    end
+
+    data = docstring.metadata.namespace(object);
+    data.name = name;
+end

mkdocstrings_handlers/matlab/matlab/+docstring/+metadata/argument.m

@@ -0,0 +1,58 @@
+function data = argument(object)
+    arguments
+        object (1,:) matlab.internal.metadata.Argument
+    end
+
+    if isempty(object)
+        data = struct.empty();
+        return
+    elseif numel(object) > 1
+       for iArg = numel(object):-1:1
+           data(iArg) = docstring.metadata.argument(object(iArg));
+       end
+       return
+    end
+
+    data.name = object.Name;
+    data.kind = string(object.Kind);
+    data.presence = string(object.Presence);
+
+    if isempty(object.DefaultValue) 
+        data.default = "";
+    elseif object.DefaultValue.IsConstant
+        data.default = string(object.DefaultValue.Value);
+    else
+        data.default = "*expression*";
+    end
+    
+    if ~isempty(object.Validation)
+        if ~isempty(object.Validation.Class)
+            data.class = string(object.Validation.Class.Name);
+        else
+            data.class = "";
+        end
+        if ~isempty(object.Validation.Size)
+            for iSize = numel(object.Validation.Size):-1:1
+
+                if isprop(object.Validation.Size(iSize), 'Length')
+                    data.size(iSize) = object.Validation.Size(iSize).Length;
+                else
+                    data.size(iSize) = ":";
+                end
+            end
+        else
+            data.size = "";
+        end
+
+        if ~isempty(object.Validation.Functions)
+            data.validators = arrayfun(@(f) string(f.Name), object.Validation.Functions);
+        else
+            data.validators = "";
+        end
+    else
+        data.class = "";
+        data.size = "";
+        data.validators = "";
+    end
+
+end

mkdocstrings_handlers/matlab/matlab/+docstring/+metadata/class.m

@@ -0,0 +1,44 @@
+function data = class(object)
+    arguments
+        object (1,1) matlab.metadata.Class
+    end
+    data.type = 'class';
+    
+    namespaces = split(object.Name, '.');
+    data.name = namespaces{end};
+    
+    data.docstring = docstring.utils.parse_doc(object, true);
+    data.path = matlab.internal.metafunction(object.Name).Location;
+    data.hidden = object.Hidden;
+    data.sealed = object.Sealed;
+    data.abstract = object.Abstract;
+    data.enumeration = object.Enumeration;
+    data.superclasses = arrayfun(@(o) string(o.Name), object.SuperclassList);
+    data.handle = object.HandleCompatible;
+    data.aliases = object.Aliases;
+    
+    data.methods = [];
+    for methodObject = object.MethodList'
+        if any(strcmp(methodObject.Name, {'empty', 'forInteractiveUse'}))
+            break
+        else
+            method.name = string(methodObject.Name);
+            method.class = string(methodObject.DefiningClass.Name);
+            method.access = methodObject.Access;
+            method.static = methodObject.Static;
+            method.abstract = methodObject.Abstract;
+            method.sealed = methodObject.Sealed;
+            method.hidden = methodObject.Hidden;
+            data.methods = [data.methods, method];
+        end
+    end
+
+    numProp = numel(object.PropertyList);
+    for iProp = numProp:-1:1
+        data.properties(iProp) = docstring.metadata.property(object.PropertyList(iProp));
+    end
+
+    nameparts = split(object.Name, '.');
+    data.constructor = any(strcmp(nameparts(end), [data.methods.name]));
+
+end

mkdocstrings_handlers/matlab/matlab/+docstring/+metadata/func.m

@@ -0,0 +1,14 @@
+function data = func(object)
+    
+    arguments
+        object (1,1) matlab.metadata.MetaData
+    end
+    
+    data.type = 'function';
+    data.name = object.Name;
+    data.docstring = docstring.utils.parse_doc(object);
+    data.path = object.Location;
+    
+    data.inputs = docstring.metadata.argument(object.Signature.Inputs);
+    data.outputs = docstring.metadata.argument(object.Signature.Outputs);
+end

mkdocstrings_handlers/matlab/matlab/+docstring/+metadata/namespace.m

@@ -0,0 +1,14 @@
+function data = namespace(object)
+    
+    arguments
+        object (1,1) matlab.metadata.Namespace
+    end
+    
+    data.type = 'namespace';
+    data.docstring = docstring.utils.parse_doc(object);
+
+    data.classes = arrayfun(@(o) string(o.Name), object.ClassList);
+    data.functions = arrayfun(@(o) string(o.Name), object.FunctionList);
+    data.namespaces = arrayfun(@(o) string(o.Name), object.InnerNamespaces);
+    data.path = docstring.utils.get_namespace_path(object);
+end

mkdocstrings_handlers/matlab/matlab/+docstring/+metadata/property.m

@@ -0,0 +1,41 @@
+function data = argument(object)
+    arguments
+        object (1,:) meta.property
+    end
+
+    data.name = string(object.Name);
+    data.class = string(object.DefiningClass.Name);
+    data.docstring = docstring.utils.parse_doc(object);
+    data.get_access = object.GetAccess;
+    data.set_access = object.SetAccess;
+    data.dependent = object.Dependent;
+    data.constant = object.Constant;
+    data.abstract = object.Abstract;
+    data.transient = object.Transient;
+    data.hidden = object.Hidden;
+
+    if ~isempty(object.Validation) && ~isempty(object.Validation.Class)
+        data.annotation = string(object.Validation.Class.Name);
+    else
+        data.annotation = "";
+    end
+
+    if ~isempty(object.Validation) && ~isempty(object.Validation.Size)
+        for iSize = numel(object.Validation.Size):-1:1
+            if isprop(object.Validation.Size(iSize), 'Length')
+                sizeStr(iSize) = string(object.Validation.Size(iSize).Length);
+            else
+                sizeStr(iSize) = ":";
+            end
+        end
+        data.size = sprintf("[%s]", join(sizeStr, ","));
+    else
+        data.size = "";
+    end
+
+    if ~isempty(object.Validation) && ~isempty(object.Validation.ValidatorFunctions)
+        data.validation = join(cellfun(@(f) string(char(f)), object.Validation.ValidatorFunctions), ", ");
+    else
+        data.validation = "";
+    end
+end

mkdocstrings_handlers/matlab/matlab/+docstring/+metadata/script.m

@@ -0,0 +1,15 @@
+function data = script(object)
+%SCRIPT Summary of this function goes here
+%   Detailed explanation goes here
+
+    arguments
+        object (1,1) matlab.metadata.MetaData
+    end
+
+    data.type = 'script';
+    data.Name = object.Name;
+    data.docstring = docstring.utils.parse_doc(object);
+    data.path = object.Location;
+
+end
+

mkdocstrings_handlers/matlab/matlab/+docstring/+utils/dedent.m

@@ -0,0 +1,34 @@
+function parsedDoc = dedent(doc)
+%DEDENT Summary of this function goes here
+%   Detailed explanation goes here
+arguments
+    doc (1,1) string
+end
+
+lines = cellstr(splitlines(doc));
+
+
+for iLine = numel(lines):-1:1
+    line = lines{iLine};
+    if ~isempty(line) && ~all(line == ' ')
+        indentations(iLine) = find(line~= ' ', 1);
+    else
+        indentations(iLine) = inf;
+    end
+end
+
+indentation = min(indentations);
+
+for iLine = 1:numel(lines)
+    line = lines{iLine};
+    if isempty(line) || numel(line) <= indentation
+        lines{iLine} = '';
+    else
+        lines{iLine} = line(indentation:end);
+    end
+end
+
+parsedDoc = string(strjoin(lines, '\n'));
+
+end
+

mkdocstrings_handlers/matlab/matlab/+docstring/+utils/get_namespace_path.m

@@ -0,0 +1,26 @@
+function path = get_namespace_path(object, parents)
+
+    arguments
+        object (1,1) matlab.metadata.Namespace
+        parents (1,1) double {mustBeInteger, mustBeNonnegative} = 0
+    end
+
+    if ~isempty(object.ClassList)
+
+        function_path = which(sprintf("%s.%s", object.Name, object.ClassList(1).Name));
+        path = fileparts(function_path);
+    elseif ~isempty(object.FunctionList)
+        
+        function_path = which(sprintf("%s.%s", object.Name, object.FunctionList(1).Name));
+        path = fileparts(function_path);
+    elseif ~isempty(object.InnerNamespaces)
+        path = docstring.utils.get_namespace_path(...
+            object.InnerNamespaces(1), parents + 1);
+    else
+        error("Cannot get path of namespace %s", object.Name);
+    end
+
+    for i = 1:parents
+        path = fileparts(path);
+    end
+end

mkdocstrings_handlers/matlab/matlab/+docstring/+utils/parse_doc.m

@@ -0,0 +1,21 @@
+function doc = parse_doc(object, combine)
+
+arguments
+    object (1,1) matlab.metadata.MetaData
+    combine (1,1) logical = false
+end
+
+if isempty(object.DetailedDescription)
+    doc = object.Description;
+else
+    if combine
+        doc = sprintf("%s\n%s", object.Description, ...
+            docstring.utils.dedent(object.DetailedDescription));
+    else
+        doc = docstring.utils.dedent(object.DetailedDescription);
+    end
+    
+end
+
+end
+

mkdocstrings_handlers/matlab/matlab/+docstring/exception.m

@@ -0,0 +1,7 @@
+function exception(identifier)
+
+    notFoundException = MException('mkdocs:callerInput', '%s %s %s', ...
+        'The input', identifier, 'could not be found on the MATLAB path');
+    throwAsCaller(notFoundException)
+
+end

mkdocstrings_handlers/matlab/matlab/+docstring/resolve.m

@@ -0,0 +1,94 @@
+function [jsonString, data] = resolve(identifier, cwd)
+% Resolve the docstring for a given MATLAB entity
+%
+% ```matlab
+% jsonString = resolve(name, cwd)
+% ```
+%
+% Parameters:
+%   identifier (string): Name of the MATLAB entity
+%   cwd (string): Current working directory
+%
+% Returns:
+%   jsonString(string): JSON-encoded metadata object
+%   data(struct): metadata object
+
+arguments
+    identifier (1, :) char
+    cwd (1,1) string {mustBeFolder} = pwd()
+end
+
+cd(cwd);
+
+% Check if namespace
+if strcmp(identifier(1), '+')
+    data = docstring.case.namespace(identifier);
+    jsonString = jsonencode(data);
+    return;
+end
+
+% Try namespace functions
+if contains(identifier, '.')
+    object = matlab.internal.metafunction(identifier);
+    if ~isempty(object) && isa(object, 'matlab.internal.metadata.Function')
+        if isempty(object.Signature)
+            data = docstring.metadata.script(object);
+        else
+            data = docstring.metadata.func(object);
+        end
+        jsonString = jsonencode(data);
+        return;
+    end
+end
+
+% Try built-in aliases with which
+if contains(which(identifier), ' built-in ')
+    data = docstring.case.builtin(identifier);
+    jsonString = jsonencode(data);
+    return
+end
+
+switch exist(identifier) %#ok<EXIST>
+    case 2
+        % if NAME is a file with extension .m, .mlx, .mlapp, or .sfx, or NAME
+        % is the name of a file with a non-registered file extension 
+        % (.mat, .fig, .txt).
+
+        % Try with metafunction
+        object = matlab.internal.metafunction(identifier);
+        if ~isempty(object) && isa(object, 'matlab.internal.metadata.Function')
+            if isempty(object.Signature)
+                data = docstring.metadata.script(object);
+            else
+                data = docstring.metadata.func(object);
+            end
+            data.name = identifier;
+        else
+            docstring.exception(identifier);
+        end
+    case 5
+        % if NAME is a built-in MATLAB function. This does not include classes
+        data = docstring.case.builtin(identifier);
+    case 8
+        % if NAME is a class (exist returns 0 for Java classes if you
+        % start MATLAB with the -nojvm option.)
+        data = docstring.case.class(identifier);
+    case 0
+        if contains(identifier, '.')
+            nameparts = split(identifier, '.');
+            tryclassname = strjoin(nameparts(1:end-1), '.');
+            if exist(tryclassname, 'class')
+                data = docstring.case.method(identifier);
+            else
+                docstring.exception(identifier);
+            end
+        else
+            docstring.exception(identifier);
+        end
+    otherwise
+        docstring.exception(identifier);
+end
+
+jsonString = jsonencode(data);
+
+end

mkdocstrings_handlers/matlab/matlab/matlab_startup.m

@@ -0,0 +1,21 @@
+function result = matlab_startup(paths, expression)
+% Add paths and evaluate an expression
+%
+% Parameters:
+%     paths (string): Paths to add to the MATLAB path
+%     expression (string): MATLAB startup expression
+
+    arguments
+        paths (1, :) string 
+        expression (1, 1) string = string.empty() 
+    end
+    for path = paths
+        addpath(genpath(path));
+    end
+
+    if ~isempty(expression)
+        eval(expression);
+    end
+
+    result = nan;
+end

mkdocstrings_handlers/matlab/models.py

@@ -0,0 +1,127 @@
+from enum import Enum
+from typing import Any
+from griffe import Function as GriffeFunction, Class as GriffeClass, Module, Attribute
+from _griffe.exceptions import BuiltinModuleError
+
+
+class Access(Enum):
+    PUBLIC = "public"
+    PROTECTED = "protected"
+    PRIVATE = "private"
+    IMMUTABLE = "immutable"
+
+
+class CanonicalPathMixin:
+    @property
+    def canonical_path(self) -> str:
+        """The full dotted path of this object.
+
+        The canonical path is the path where the object was defined (not imported).
+        """
+        if self.parent is None or self.parent.path == "":
+            return self.name
+        return f"{self.parent.path}.{self.name}"
+
+
+class Class(CanonicalPathMixin, GriffeClass):
+    def __init__(
+        self,
+        *args: Any,
+        hidden: bool = False,
+        sealed: bool = False,
+        abstract: bool = False,
+        enumeration: bool = False,
+        handle: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self._hidden: bool = hidden
+        self._sealed: bool = sealed
+        self._abstract: bool = abstract
+        self._enumeration: bool = enumeration
+        self._handle: bool = handle
+
+    @property
+    def is_private(self) -> bool:
+        return self._hidden
+
+    @property
+    def canonical_path(self) -> str:
+        if isinstance(self.parent, Classfolder):
+            return self.parent.canonical_path
+        else:
+            return super().canonical_path
+
+
+class Property(CanonicalPathMixin, Attribute):
+    def __init__(
+        self,
+        *args: Any,
+        get_access: Access = Access.PUBLIC,
+        set_access: Access = Access.PUBLIC,
+        dependent: bool = False,
+        constant: bool = False,
+        abstract: bool = False,
+        transient: bool = False,
+        hidden: bool = False,
+        get_observable: bool = False,
+        set_observable: bool = False,
+        abort_set: bool = False,
+        non_copyable: bool = False,
+        has_default: bool = False,
+        size: str | None = None,
+        validation: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self._get_access: Access = get_access
+        self._set_access: Access = set_access
+        self._dependent: bool = dependent
+        self._constant: bool = constant
+        self._abstract: bool = abstract
+        self._transient: bool = transient
+        self._hidden: bool = hidden
+        self._get_observable: bool = get_observable
+        self._set_observable: bool = set_observable
+        self._abort_set: bool = abort_set
+        self._non_copyable: bool = non_copyable
+        self._has_default: bool = has_default
+        self._size: str | None = size
+        self._validation: str | None = validation
+
+    @property
+    def is_private(self) -> bool:
+        set_public = self._access == Access.PUBLIC | self._access == Access.IMMUTABLE
+        get_public = self._access == Access.PUBLIC
+        return (set_public or get_public) and not self._hidden
+
+
+class Function(CanonicalPathMixin, GriffeFunction):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._access: Access = Access.PUBLIC
+        self._static: bool = False
+        self._abstract: bool = False
+        self._sealed: bool = False
+        self._hidden: bool = False
+
+    @property
+    def is_private(self) -> bool:
+        public = self._access == Access.PUBLIC | self._access == Access.IMMUTABLE
+        return public and not self._hidden
+
+
+class Namespace(CanonicalPathMixin, Module):
+    def __repr__(self) -> str:
+        try:
+            return f"Namespace({self.filepath!r})"
+        except BuiltinModuleError:
+            return f"Namespace({self.name!r})"
+
+
+class Classfolder(CanonicalPathMixin, Module):
+    def __repr__(self) -> str:
+        try:
+            return f"Classfolder({self.filepath!r})"
+        except BuiltinModuleError:
+            return f"Classfolder({self.name!r})"

mkdocstrings_matlab-0.1.0.dist-info/METADATA

@@ -0,0 +1,17 @@
+Metadata-Version: 2.3
+Name: mkdocstrings-matlab
+Version: 0.1.0
+Summary: Add your description here
+Author-email: Mark Hu <mark.hu@asml.com>
+License-File: LICENSE
+Requires-Dist: griffe>=1.2.0
+Requires-Dist: markdown>=3.7
+Requires-Dist: mkdocs-material>=9.5.33
+Requires-Dist: mkdocs>=1.6.0
+Requires-Dist: mkdocstrings>=0.25.2
+Requires-Dist: mkdocstrings[python]>=0.18
+Description-Content-Type: text/markdown
+
+# mkdocstrings-matlab
+
+Describe your project here.

mkdocstrings_matlab-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+mkdocstrings_handlers/matlab/__init__.py,sha256=laA2bEP5rxdIWBLmfLiKKu7ChZ_HzCe-VeRvxmUTqww,128
+mkdocstrings_handlers/matlab/handler.py,sha256=GuFjY7Jrv9QnHZELWghzAXEBf6Z67xvYr7aLPxMGvAg,14294
+mkdocstrings_handlers/matlab/models.py,sha256=-k5V6Usho9D8KAynvEnMz7B6Fyrf1TrkJ1P8NhRdyzQ,3997
+mkdocstrings_handlers/matlab/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkdocstrings_handlers/matlab/matlab/matlab_startup.m,sha256=rGXiR8fI2GW7yWmHxgzE5Un66n5ws3ogYnMvS2oWO8U,464
+mkdocstrings_handlers/matlab/matlab/+docstring/exception.m,sha256=sj2ycqMpknn_OG5A5X_b5e4WcAoR2oPoqNnDEHJsi7c,222
+mkdocstrings_handlers/matlab/matlab/+docstring/resolve.m,sha256=ZHHz6ujW1godzDcGtC3p0SsVARv-roseUh85e2eTBrE,2736
+mkdocstrings_handlers/matlab/matlab/+docstring/+case/builtin.m,sha256=IioiokiaLnsi_6VXraaGdU2AgjCNApYhgVEmp2Lg1eA,245
+mkdocstrings_handlers/matlab/matlab/+docstring/+case/class.m,sha256=MXeRhQibRQSOYwbrmc9tHLS723baStzSf9yXfzSEri0,275
+mkdocstrings_handlers/matlab/matlab/+docstring/+case/func.m,sha256=QneDYSICtXqdPNq8sYNieirXUisuDKRM9rxPx-0osDU,137
+mkdocstrings_handlers/matlab/matlab/+docstring/+case/method.m,sha256=Bw8Mb96OP7-AnbGnvRMySOIbYSTtEC1BGBnqHMEIhsM,165
+mkdocstrings_handlers/matlab/matlab/+docstring/+case/namespace.m,sha256=ZpYrgZHLIdGvgg3F6210gDTska9YyASn63ZVYkBq41A,667
+mkdocstrings_handlers/matlab/matlab/+docstring/+metadata/argument.m,sha256=l6UIQ4uolz533vo5DDWxl0R5PRkbb6hpRxpMPu5SNm8,1583
+mkdocstrings_handlers/matlab/matlab/+docstring/+metadata/class.m,sha256=KurAMy-D_-47CYCdrqvzlSDXIl_dB2gwIQPLzjai35s,1542
+mkdocstrings_handlers/matlab/matlab/+docstring/+metadata/func.m,sha256=urjYQauSRZ9bXg4co4gurOmiKzj5Sc4IS8FRKU8eEHM,408
+mkdocstrings_handlers/matlab/matlab/+docstring/+metadata/namespace.m,sha256=kMzfAoWIpMXH76rrkyUqauJSRIaylsfnu0Cds4pYnJc,481
+mkdocstrings_handlers/matlab/matlab/+docstring/+metadata/property.m,sha256=Ro5jciF60k8YRjJ_GWSm0kJNVZPfh4kyyLvYOwhrL2o,1379
+mkdocstrings_handlers/matlab/matlab/+docstring/+metadata/script.m,sha256=pmuazWBqlugNEEojfQFkAg1ioErizoiEZ9RcFXecCP4,329
+mkdocstrings_handlers/matlab/matlab/+docstring/+utils/dedent.m,sha256=r02mWQkRP9uuoEl-f-02h1-ja17a_29LTeyJvK-kazI,669
+mkdocstrings_handlers/matlab/matlab/+docstring/+utils/get_namespace_path.m,sha256=4NlQ7-RjqIFZAn6P-9JzCrm2FvfGRKiM2M_leINj9i4,835
+mkdocstrings_handlers/matlab/matlab/+docstring/+utils/parse_doc.m,sha256=z1voyYnASblb2i98n4dySOmBIbCa3n9moQKtbR5WE-k,442
+mkdocstrings_matlab-0.1.0.dist-info/METADATA,sha256=R5KTt_IHagwweU_hC78Od6DXPiTfNOkE6S0IiDqqNeU,457
+mkdocstrings_matlab-0.1.0.dist-info/WHEEL,sha256=fl6v0VwpzfGBVsGtkAkhILUlJxROXbA3HvRL6Fe3140,105
+mkdocstrings_matlab-0.1.0.dist-info/licenses/LICENSE,sha256=14xA0OIYNpfmdeuq8-Yyqg7-3IJ4qhu3BJhknent-cY,1069
+mkdocstrings_matlab-0.1.0.dist-info/RECORD,,

mkdocstrings_matlab-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any

mkdocstrings_matlab-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mark Shui Hu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.