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

mkdocstrings_handlers/matlab/handler.py

@@ -12,11 +12,29 @@ import json
 
 
 from mkdocstrings_handlers.matlab_engine import MatlabEngine, MatlabExecutionError
-from mkdocstrings_handlers.matlab.models import Function, Class, Classfolder, Namespace, Property
+from mkdocstrings_handlers.matlab.models import (
+    Function,
+    Class,
+    Classfolder,
+    Namespace,
+    Property,
+    ROOT
+)
 
 
-ROOT_NAMESPACE = Namespace("", filepath="")
-MODELS = {}
+class _ModelsStorage:
+    def __init__(self):
+        self._namespace = ""
+        self._models = {}
+
+    def __getitem__(self, key):
+        return self._models[key]
+
+    def __setitem__(self, key, value):
+        self._models[key] = value
+
+    def __contains__(self, key):
+        return key in self._models
 
 
 class MatlabHandler(BaseHandler):
@@ -71,8 +89,8 @@ class MatlabHandler(BaseHandler):
         # Member options
         "inherited_members": False,
         "members": None,
-        "members_order": rendering.Order.alphabetical.value,
-        "filters": ["!^_[^_]"],
+        "members_order": rendering.Order.alphabetical,
+        "filters": [],
         "group_by_category": True,
         "show_submodules": False,
         "summary": False,
@@ -102,7 +120,7 @@ class MatlabHandler(BaseHandler):
         "show_signature": True,
         "show_signature_annotations": False,
         "signature_crossrefs": False,
-        "separate_signature": True,
+        "separate_signature": False,
         "unwrap_annotated": False,
         "modernize_annotations": False,
     }
@@ -124,6 +142,7 @@ class MatlabHandler(BaseHandler):
         self.engine = MatlabEngine()
         self.engine.addpath(str(Path(__file__).parent / "matlab"))
         self.engine.matlab_startup(paths, startup_expression)
+        self.models = _ModelsStorage()
         self._locale = locale
 
     def get_templates_dir(self, handler: str | None = None) -> Path:
@@ -145,6 +164,9 @@ class MatlabHandler(BaseHandler):
             CollectorItem
         """
         final_config = ChainMap(config, self.default_config)  # type: ignore[arg-type]
+        if identifier in self.models:
+            return self.models[identifier]
+
         try:
             ast_json = self.engine.docstring.resolve(identifier)
         except MatlabExecutionError as error:
@@ -152,10 +174,8 @@ class MatlabHandler(BaseHandler):
         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 "function" | "method":
+                return self.collect_function(ast_dict, final_config)
             case "class":
                 return self.collect_class(ast_dict, final_config)
             case _:
@@ -229,25 +249,24 @@ class MatlabHandler(BaseHandler):
             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(
+        model = Class(
             ast_dict["name"],
             docstring=docstring,
-            parent=get_parent(Path(ast_dict["path"]).parent),
+            parent=self.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"],
+            filepath=Path(ast_dict["path"]),
         )
 
-
         for property_dict in ast_dict["properties"]:
             name = property_dict.pop("name")
             defining_class = property_dict.pop("class")
@@ -257,92 +276,111 @@ class MatlabHandler(BaseHandler):
                 if property_doc
                 else None
             )
-            if defining_class != object.canonical_path and not config["inherited_members"]:
+            if (
+                defining_class != model.canonical_path
+                and not config["inherited_members"]
+            ):
                 continue
 
-            object.members[name] = Property(name, docstring=docstring, **property_dict)
+            prop = Property(name, docstring=docstring, parent=model, **property_dict)
+            model.members[name] = prop
+            self.models[prop.canonical_path] = prop
 
         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"]:
+            if (
+                defining_class != model.canonical_path
+                and not config["inherited_members"]
+            ):
                 continue
-            
+
             method = self.collect(f"{defining_class}.{name}", config)
+            method.parent = model
             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"]
+            model.members[name] = method
+            self.models[method.canonical_path] = method
 
-            object.members[name] = method
+        if config["merge_init_into_class"] and model.name in model.members:
+            constructor = model.members.pop(model.name)
+            model.members["__init__"] = constructor
+            if constructor.docstring.value == model.docstring.value:
+                model.docstring = None
 
-        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
+        self.models[model.canonical_path] = model
 
+        return model
 
+    def collect_function(self, 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,
+                )
+            )
 
+        model = 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=self.get_parent(Path(ast_dict["path"]).parent),
+            filepath=Path(ast_dict["path"]),
+        )
 
-def collect_function(ast_dict: dict, config: Mapping) -> Function:
-    parameters = []
+        self.models[model.canonical_path] = model
+        return model
 
-    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,
+    def get_parent(self, path: Path) -> Namespace | Classfolder:
+        if path.stem[0] == "+":
+            parent = Namespace(
+                path.stem[1:], filepath=path, parent=self.get_parent(path.parent)
             )
-        )
+            identifier = parent.canonical_path
+            if identifier in self.models:
+                parent = self.models[identifier]
+            else:
+                self.models[identifier] = parent
 
-    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),
-    )
+        elif path.stem[0] == "@":
+            parent = Classfolder(
+                path.stem[1:], filepath=path, parent=self.get_parent(path.parent)
+            )
+            identifier = parent.canonical_path
+            if identifier in self.models:
+                parent = self.models[identifier]
+            else:
+                self.models[identifier] = parent
 
-    return func
+        else:
+            parent = ROOT
+        return parent
 
 
 def get_handler(

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

@@ -17,12 +17,21 @@ function data = argument(object)
     data.kind = string(object.Kind);
     data.presence = string(object.Presence);
 
-    if isempty(object.DefaultValue) 
+    if contains(data.presence, ["required", "unspecified"])
         data.default = "";
-    elseif object.DefaultValue.IsConstant
-        data.default = string(object.DefaultValue.Value);
     else
-        data.default = "*expression*";
+        if ~isempty(object.DefaultValue) && object.DefaultValue.IsConstant
+            value = object.DefaultValue.Value;
+            if strcmp(value, "")
+                data.default = """""";
+            elseif isstring(value) || ischar(value)
+                data.default = sprintf("'%s'", value);
+            else
+                data.default = string(value);
+            end
+        else
+            data.default = "...";
+        end
     end
     
     if ~isempty(object.Validation)

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

@@ -7,7 +7,7 @@ function data = class(object)
     namespaces = split(object.Name, '.');
     data.name = namespaces{end};
     
-    data.docstring = docstring.utils.parse_doc(object, true);
+    data.docstring = docstring.utils.parse_doc(object);
     data.path = matlab.internal.metafunction(object.Name).Location;
     data.hidden = object.Hidden;
     data.sealed = object.Sealed;
@@ -24,7 +24,11 @@ function data = class(object)
         else
             method.name = string(methodObject.Name);
             method.class = string(methodObject.DefiningClass.Name);
-            method.access = methodObject.Access;
+            if iscell(methodObject.Access)
+                method.access = "private";
+            else
+                method.access = methodObject.Access;
+            end
             method.static = methodObject.Static;
             method.abstract = methodObject.Abstract;
             method.sealed = methodObject.Sealed;

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

@@ -1,4 +1,4 @@
-function data = argument(object)
+function data = property(object)
     arguments
         object (1,:) meta.property
     end
@@ -6,8 +6,17 @@ function data = argument(object)
     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;
+
+    if iscell(object.GetAccess)
+        data.get_access = 'private';
+    else
+        data.get_access = object.GetAccess;
+    end
+    if iscell(object.SetAccess)
+        data.set_access = 'private';
+    else
+        data.set_access = object.SetAccess;
+    end
     data.dependent = object.Dependent;
     data.constant = object.Constant;
     data.abstract = object.Abstract;

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

@@ -2,10 +2,10 @@ function doc = parse_doc(object, combine)
 
 arguments
     object (1,1) matlab.metadata.MetaData
-    combine (1,1) logical = false
+    combine (1,1) logical = true
 end
 
-if isempty(object.DetailedDescription)
+if isempty(object.DetailedDescription) || strcmp(object.DetailedDescription, "")
     doc = object.Description;
 else
     if combine

mkdocstrings_handlers/matlab/models.py

@@ -2,6 +2,7 @@ from enum import Enum
 from typing import Any
 from griffe import Function as GriffeFunction, Class as GriffeClass, Module, Attribute
 from _griffe.exceptions import BuiltinModuleError
+from pathlib import Path
 
 
 class Access(Enum):
@@ -18,12 +19,22 @@ class CanonicalPathMixin:
 
         The canonical path is the path where the object was defined (not imported).
         """
-        if self.parent is None or self.parent.path == "":
+        if isinstance(self.parent, _Root):
             return self.name
         return f"{self.parent.path}.{self.name}"
 
 
-class Class(CanonicalPathMixin, GriffeClass):
+class PathMixin:
+    def __init__(self, *args: Any, filepath: Path | None = None, **kwargs: Any) -> None:
+        self._filepath: Path | None = filepath
+        super().__init__(*args, **kwargs)
+
+    @property
+    def filepath(self) -> Path | None:
+        return self._filepath
+
+
+class Class(CanonicalPathMixin, PathMixin, GriffeClass):
     def __init__(
         self,
         *args: Any,
@@ -96,7 +107,7 @@ class Property(CanonicalPathMixin, Attribute):
         return (set_public or get_public) and not self._hidden
 
 
-class Function(CanonicalPathMixin, GriffeFunction):
+class Function(CanonicalPathMixin, PathMixin, GriffeFunction):
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
         self._access: Access = Access.PUBLIC
@@ -111,17 +122,30 @@ class Function(CanonicalPathMixin, GriffeFunction):
         return public and not self._hidden
 
 
-class Namespace(CanonicalPathMixin, Module):
+class Namespace(CanonicalPathMixin, PathMixin, Module):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._access: Access = Access.PUBLIC
+
+    def __repr__(self) -> str:
+        return f"Namespace({self.path!r})"
+
+
+class _Root(Namespace):
+    def __init__(self) -> None:
+        super().__init__("ROOT", parent=None)
+
     def __repr__(self) -> str:
-        try:
-            return f"Namespace({self.filepath!r})"
-        except BuiltinModuleError:
-            return f"Namespace({self.name!r})"
+        return "MATLABROOT"
+    
+
+ROOT = _Root()
 
 
-class Classfolder(CanonicalPathMixin, Module):
+class Classfolder(Class):
     def __repr__(self) -> str:
-        try:
-            return f"Classfolder({self.filepath!r})"
-        except BuiltinModuleError:
-            return f"Classfolder({self.name!r})"
+        return f"Classfolder({self.path!r})"
+
+
+
+

{mkdocstrings_matlab-0.1.0.dist-info → mkdocstrings_matlab-0.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: mkdocstrings-matlab
-Version: 0.1.0
+Version: 0.1.1
 Summary: Add your description here
 Author-email: Mark Hu <mark.hu@asml.com>
 License-File: LICENSE

{mkdocstrings_matlab-0.1.0.dist-info → mkdocstrings_matlab-0.1.1.dist-info}/RECORD

@@ -1,6 +1,6 @@
 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/handler.py,sha256=078JkZgLNGIbTmGGhzQfKWjPLdw79Jf1d9Vj_hG6rgY,15721
+mkdocstrings_handlers/matlab/models.py,sha256=9oK-ZmpQuU2cU2wX8wlaK540BB9LazzaCtTmnnnIDyo,4428
 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
@@ -10,16 +10,16 @@ mkdocstrings_handlers/matlab/matlab/+docstring/+case/class.m,sha256=MXeRhQibRQSO
 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/argument.m,sha256=xfshXZas8h0oZ2od5b6hW_f4_-u_XmiJSS52XiAOaC4,1906
+mkdocstrings_handlers/matlab/matlab/+docstring/+metadata/class.m,sha256=NjJxS1Kn5Bhbfk_W-0ySs3gJ5ImrEClkns8w7Fs-g9E,1659
 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/property.m,sha256=rH3cHz66ZG9sUvDU2fhlyASSB_yp0SiHlbpB44fcFiY,1560
 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_handlers/matlab/matlab/+docstring/+utils/parse_doc.m,sha256=6pGRMZSPrqaI5C0LNan342-Dje5tneDwUPkUJ_cMiSA,483
+mkdocstrings_matlab-0.1.1.dist-info/METADATA,sha256=I4RLFAZMluugnZ1sefZSDCGRF4_s5ETUav-_o7yFtw8,457
+mkdocstrings_matlab-0.1.1.dist-info/WHEEL,sha256=fl6v0VwpzfGBVsGtkAkhILUlJxROXbA3HvRL6Fe3140,105
+mkdocstrings_matlab-0.1.1.dist-info/licenses/LICENSE,sha256=14xA0OIYNpfmdeuq8-Yyqg7-3IJ4qhu3BJhknent-cY,1069
+mkdocstrings_matlab-0.1.1.dist-info/RECORD,,