mkdocstrings-matlab 0.1.7__tar.gz → 0.2.1__tar.gz

{mkdocstrings_matlab-0.1.7 → mkdocstrings_matlab-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: mkdocstrings-matlab
-Version: 0.1.7
+Version: 0.2.1
 Summary: Add your description here
 Author-email: Mark Hu <watermarkhu@gmail.com>
 License-File: LICENSE

{mkdocstrings_matlab-0.1.7 → mkdocstrings_matlab-0.2.1}/mkdocs.yml

@@ -23,6 +23,6 @@ plugins:
       #     show_root_heading: true
       #     show_docstring_attributes: false
       matlab:
-        paths: ["/home/mahu/repositories/github-matlab-test-action/src"]
+        paths: ["/home/mahu/repositories/matlab-test-action/src"]
         options:
           show_root_heading: true

{mkdocstrings_matlab-0.1.7 → mkdocstrings_matlab-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocstrings-matlab"
-version = "0.1.7"
+version = "0.2.1"
 description = "Add your description here"
 authors = [
     { name = "Mark Hu", email = "watermarkhu@gmail.com" }

{mkdocstrings_matlab-0.1.7 → mkdocstrings_matlab-0.2.1}/src/mkdocstrings_handlers/matlab/handler.py

@@ -10,6 +10,7 @@ from pprint import pprint
 
 import charset_normalizer
 import json
+import requests
 
 
 from mkdocstrings_handlers.matlab.collections import LinesCollection, ModelsCollection
@@ -60,7 +61,8 @@ class MatlabHandler(BaseHandler):
         # "find_stubs_package": False,
         # "allow_inspection": True,
         "show_bases": True,
-        "show_inheritance_diagram": False,  # Insider feature
+        "show_inheritance_diagram": True,
+        "inheritance_diagram_show_builtin": False,
         "show_source": True,
         # "preload_modules": None,
         # Heading options
@@ -143,6 +145,50 @@ class MatlabHandler(BaseHandler):
         # (it assumes the python handler is installed)
         return super().get_templates_dir("python")
 
+    def get_ast(self, identifier:str, config: Mapping[str, Any]) -> dict:
+        """Retrieve the Abstract Syntax Tree (AST) for a given MATLAB identifier.
+        
+        This method resolves the docstring for the specified identifier and parses it into an AST.
+        If the identifier corresponds to a class, it processes its superclasses and optionally 
+        includes an inheritance diagram based on the provided configuration.
+        Args:
+            identifier (str): The MATLAB identifier to resolve.
+            config (Mapping[str, Any]): Configuration options for processing the AST.
+        Returns:
+            dict: The parsed AST for the given identifier.
+        Raises:
+            MatlabExecutionError: If there is an error resolving the superclass AST.
+        """
+
+        ast_json = self.engine.docstring.resolve(identifier)
+        ast = json.loads(ast_json)
+
+        if ast['type'] == 'class':
+            
+            if isinstance(ast["superclasses"], str):
+                ast["superclasses"] = [ast["superclasses"]]
+            if isinstance(ast["properties"], dict):
+                ast["properties"] = [ast["properties"]]
+            if isinstance(ast["methods"], dict):
+                ast["methods"] = [ast["methods"]]
+            
+            if config["show_inheritance_diagram"]:
+                # Check if class is builtin and skip superclasses if option is not set
+                builtin = ast.get('builtin', False) or ast["name"].startswith("matlab.")
+                resursive = not builtin or config["inheritance_diagram_show_builtin"]
+                if not resursive:
+                    ast["superclasses"] = []
+
+                # Get superclasses AST
+                for index, base in enumerate(ast["superclasses"]):
+                    try:
+                        ast["superclasses"][index] = self.get_ast(base, config)
+                        ast["superclasses"][index]["name"] = base
+                    except MatlabExecutionError:
+                        ast["superclasses"][index] = {"name": base}
+        return ast
+
+
     def collect(self, identifier: str, config: Mapping[str, Any]) -> CollectorItem:
         """Collect data given an identifier and user configuration.
 
@@ -156,26 +202,28 @@ class MatlabHandler(BaseHandler):
         Returns:
             CollectorItem
         """
+        if identifier == "":
+            raise CollectionError("Empty identifier")
+
         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)
+            ast = self.get_ast(identifier, final_config)
         except MatlabExecutionError as error:
             raise CollectionError(error.args[0].strip()) from error
-        ast_dict = json.loads(ast_json)
 
-        filepath = Path(ast_dict["path"])
+        filepath = Path(ast["path"])
         if filepath not in self.lines:
             lines = str(charset_normalizer.from_path(filepath).best()).splitlines()
             self.lines[filepath] = lines
 
-        match ast_dict["type"]:
+        match ast["type"]:
             case "function" | "method":
-                return self.collect_function(ast_dict, final_config)
+                return self.collect_function(ast, final_config)
             case "class":
-                return self.collect_class(ast_dict, final_config)
+                return self.collect_class(ast, final_config)
             case _:
                 return None
 
@@ -247,15 +295,11 @@ 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
-        )
+    def collect_class(self, ast: dict, config: Mapping) -> Class:
 
-        filepath = Path(ast_dict["path"])
+        filepath = Path(ast["path"])
 
+        # Parse textmate object
         if config["show_source"]:
             tmObject = self.parser.parse_file(filepath)
             tmClass = next(
@@ -266,18 +310,24 @@ class MatlabHandler(BaseHandler):
         else:
             tmClass = None
 
-        bases = ast_dict["superclasses"] if isinstance(ast_dict["superclasses"], list) else [ast_dict["superclasses"]]
-        bases = [base for base in bases if base != "handle"]
-
+        # Get bases
+        if config["show_bases"]:
+            if config["show_inheritance_diagram"]:
+                bases = [base["name"] for base in ast["superclasses"]]
+            else:
+                bases = ast["superclasses"] if isinstance(ast["superclasses"], list) else [ast["superclasses"]]
+        else:
+            bases = []
+        
+        # Load model
         model = Class(
-            ast_dict["name"],
-            docstring=docstring,
+            ast["name"],
             parent=self.get_parent(filepath.parent),
-            hidden=ast_dict["hidden"],
-            sealed=ast_dict["sealed"],
-            abstract=ast_dict["abstract"],
-            enumeration=ast_dict["enumeration"],
-            handle=ast_dict["handle"],
+            hidden=ast["hidden"],
+            sealed=ast["sealed"],
+            abstract=ast["abstract"],
+            enumeration=ast["enumeration"],
+            handle=ast["handle"],
             bases=bases,
             filepath=filepath,
             modules_collection=self.models,
@@ -286,8 +336,21 @@ class MatlabHandler(BaseHandler):
             endlineno=len(self.lines[filepath]),
             textmate=tmClass,
         )
+        ast["name"] = model.canonical_path
+
+        # Format mermaid inheritance diagram
+        if config["show_inheritance_diagram"] and ast["superclasses"]:
+            section = get_inheritance_diagram(ast)
+            docstring = Docstring(ast["docstring"] + section, parser=config["docstring_style"])
+        elif ast["docstring"]:
+            docstring = Docstring(ast["docstring"], parser=config["docstring_style"])
+        else:
+            docstring = None
 
-        for property_dict in ast_dict["properties"]:
+        model.docstring = docstring
+
+        # Load properties
+        for property_dict in ast["properties"]:
             name = property_dict.pop("name")
             defining_class = property_dict.pop("class")
             property_doc = property_dict.pop("docstring")
@@ -306,7 +369,8 @@ class MatlabHandler(BaseHandler):
             model.members[name] = prop
             self.models[prop.canonical_path] = prop
 
-        for method_dict in ast_dict["methods"]:
+        # Load methods
+        for method_dict in ast["methods"]:
             name = method_dict.pop("name")
             defining_class = method_dict.pop("class")
             if (
@@ -330,20 +394,21 @@ class MatlabHandler(BaseHandler):
         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:
+
+            if getattr(constructor.docstring, 'value', '') == getattr(model.docstring, 'value', ''):
                 model.docstring = None
 
         self.models[model.canonical_path] = model
 
         return model
 
-    def collect_function(self, ast_dict: dict, config: Mapping) -> Function:
+    def collect_function(self, ast: dict, config: Mapping) -> Function:
         parameters = []
 
         inputs = (
-            ast_dict["inputs"]
-            if isinstance(ast_dict["inputs"], list)
-            else [ast_dict["inputs"]]
+            ast["inputs"]
+            if isinstance(ast["inputs"], list)
+            else [ast["inputs"]]
         )
         for input_dict in inputs:
             if input_dict["name"] == "varargin":
@@ -362,16 +427,16 @@ class MatlabHandler(BaseHandler):
                 )
             )
 
-        filepath = Path(ast_dict["path"])
+        filepath = Path(ast["path"])
         model = Function(
-            ast_dict["name"],
+            ast["name"],
             parameters=Parameters(*parameters),
             docstring=Docstring(
-                ast_dict["docstring"],
+                ast["docstring"],
                 parser=config["docstring_style"],
                 parser_options=config["docstring_options"],
             )
-            if ast_dict["docstring"]
+            if ast["docstring"]
             else None,
             parent=self.get_parent(filepath.parent),
             filepath=filepath,
@@ -409,6 +474,32 @@ class MatlabHandler(BaseHandler):
             parent = ROOT
         return parent
 
+def get_inheritance_diagram(ast: dict) -> str:
+    def get_id(str: str) -> str:
+        return str.replace('.', '_')
+    def get_nodes(ast: dict, nodes: set[str] = set(), clicks: set[str] = set()) -> str:
+        id = get_id(ast['name'])
+        nodes.add(f"   {id}[{ast['name']}]")
+        if "help" in ast:
+            clicks.add(f"   click {id} \"{ast['help']}\"")
+        if "superclasses" in ast:
+            for superclass in ast["superclasses"]:
+                get_nodes(superclass, nodes)
+        return (nodes, clicks)
+    def get_links(ast: dict, links: set[str] = set()) -> str:
+        if "superclasses" in ast:
+            for superclass in ast["superclasses"]:
+                links.add(f"   {get_id(ast['name'])} --> {get_id(superclass['name'])}")
+                get_links(superclass, links)
+        return links
+    
+    (nodes, clicks) = get_nodes(ast)
+    nodes_str = '\n'.join(list(nodes))
+    clicks_str = '\n'.join(list(clicks))
+    links_str = '\n'.join(list(get_links(ast)))
+    section = f"\n\n## Inheritance diagram\n\n```mermaid\nflowchart BT\n{nodes_str}\n{clicks_str}\n{links_str}\n```"
+    return section
+
 
 def get_handler(
     *,

mkdocstrings_matlab-0.2.1/src/mkdocstrings_handlers/matlab/matlab/+docstring/+case/builtin.m

@@ -0,0 +1,27 @@
+function data = builtin(identifier)
+    if isMATLABReleaseOlderThan('R2024a')
+        metaclass = @meta.class.fromName;
+    else
+        metaclass = @matlab.metadata.Class.fromName;
+    end
+
+    object = metaclass(identifier);
+
+    if isempty(object)
+        data.name = identifier;
+        data.type = 'function';
+        data.doc = help(identifier);
+        data.location = string(which(identifier));
+        data.inputs = struct.empty();
+        data.outputs = struct.empty();
+        if ~contains(identifier, '.internal.')
+            data.help = sprintf('https://mathworks.com/help/matlab/ref/%s.html', lower(identifier));
+        end
+    else
+        data = docstring.metadata.class(object, 'builtin', true);
+        if ~contains(identifier, '.internal.')
+            data.help = sprintf('https://mathworks.com/help/matlab/ref/%s-class.html', lower(identifier));
+        end
+    end
+    data.builtin = true;
+end

{mkdocstrings_matlab-0.1.7 → mkdocstrings_matlab-0.2.1}/src/mkdocstrings_handlers/matlab/matlab/+docstring/+metadata/class.m

@@ -1,6 +1,7 @@
-function data = class(object)
+function data = class(object, opts)
     arguments
         object (1,1) % meta.class matlab.metadata.Class
+        opts.builtin (1,1) logical = false
     end
     data.type = 'class';
     
@@ -8,7 +9,6 @@ function data = class(object)
     data.name = namespaces{end};
     
     data.docstring = docstring.utils.parse_doc(object);
-    data.path = matlab.internal.metafunction(object.Name).Location;
     data.hidden = object.Hidden;
     data.sealed = object.Sealed;
     data.abstract = object.Abstract;
@@ -16,6 +16,11 @@ function data = class(object)
     data.superclasses = arrayfun(@(o) string(o.Name), object.SuperclassList);
     data.handle = object.HandleCompatible;
     data.aliases = object.Aliases;
+    if opts.builtin
+        data.path = '';
+    else
+        data.path = matlab.internal.metafunction(object.Name).Location;
+    end
     
     data.methods = [];
     for methodObject = object.MethodList'

{mkdocstrings_matlab-0.1.7 → mkdocstrings_matlab-0.2.1}/src/mkdocstrings_handlers/matlab/matlab/+docstring/resolve.m

@@ -46,7 +46,7 @@ if contains(identifier, '.')
 end
 
 % Try built-in aliases with which
-if contains(which(identifier), ' built-in ')
+if contains(which(identifier), {' built-in ', matlabroot})
     data = docstring.case.builtin(identifier);
     jsonString = jsonencode(data);
     return

{mkdocstrings_matlab-0.1.7 → mkdocstrings_matlab-0.2.1}/src/mkdocstrings_handlers/matlab/models.py

@@ -62,7 +62,7 @@ class Class(CanonicalPathMixin, PathMixin, GriffeClass):
             for block in self._textmate.children
             if block.token == "meta.methods.matlab"
         ]:
-            for method in block.children:
+            for method in [c for c in block.children if c.token == "meta.function.matlab"]:
                 declaration = next(
                     item
                     for item in method.children

{mkdocstrings_matlab-0.1.7 → mkdocstrings_matlab-0.2.1}/submodules/mkdocstrings-matlab-r2023a/pyproject.toml

@@ -35,8 +35,8 @@ classifiers = [
 
 [project.urls]
 Documentation = "http://watermarkhu.nl/mkdocstrings-matlab/"
-Repository = "https://github.com/watermarkhu/mkdocstrings-matlab-r2023a"
-Issues = "https://github.com/watermarkhu/mkdocstrings-matla-r2023a/issues"
+Repository = "https://github.com/watermarkhu/mkdocstrings-matlab"
+Issues = "https://github.com/watermarkhu/mkdocstrings-matlab/issues"
 
 
 [build-system]

{mkdocstrings_matlab-0.1.7 → mkdocstrings_matlab-0.2.1}/submodules/mkdocstrings-matlab-r2023b/pyproject.toml

@@ -35,8 +35,8 @@ classifiers = [
 
 [project.urls]
 Documentation = "http://watermarkhu.nl/mkdocstrings-matlab/"
-Repository = "https://github.com/watermarkhu/mkdocstrings-matlab-r2023b"
-Issues = "https://github.com/watermarkhu/mkdocstrings-matla-r2023b/issues"
+Repository = "https://github.com/watermarkhu/mkdocstrings-matlab"
+Issues = "https://github.com/watermarkhu/mkdocstrings-matlab/issues"
 
 [build-system]
 requires = ["hatchling"]

{mkdocstrings_matlab-0.1.7 → mkdocstrings_matlab-0.2.1}/submodules/mkdocstrings-matlab-r2024a/pyproject.toml

@@ -35,8 +35,8 @@ classifiers = [
 
 [project.urls]
 Documentation = "http://watermarkhu.nl/mkdocstrings-matlab/"
-Repository = "https://github.com/watermarkhu/mkdocstrings-matlab-r2024a"
-Issues = "https://github.com/watermarkhu/mkdocstrings-matla-r2024a/issues"
+Repository = "https://github.com/watermarkhu/mkdocstrings-matlab"
+Issues = "https://github.com/watermarkhu/mkdocstrings-matlab/issues"
 
 [build-system]
 requires = ["hatchling"]

mkdocstrings_matlab-0.2.1/submodules/mkdocstrings-matlab-r2024b/.gitignore

@@ -0,0 +1,10 @@
+# python generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# venv
+.venv

mkdocstrings_matlab-0.2.1/submodules/mkdocstrings-matlab-r2024b/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.

mkdocstrings_matlab-0.2.1/submodules/mkdocstrings-matlab-r2024b/README.md

@@ -0,0 +1,4 @@
+# mkdocstrings-matlab-r2024b
+
+Submodule for [mkdocstrings-matlab](https://pypi.org/project/mkdocstrings-matlab/) required for compatiblity with MATLAB R2024b. 
+

mkdocstrings_matlab-0.2.1/submodules/mkdocstrings-matlab-r2024b/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "mkdocstrings-matlab-r2024b"
+version = "0.1.2"
+description = "Add your description here"
+authors = [
+    { name = "Mark Shui Hu", email = "watermarkhu@gmail.com" }
+]
+dependencies = [
+    "matlabengine==24.2.1",
+]
+readme = "README.md"
+requires-python = ">=3.9,<3.13"
+keywords = ["mkdocs", "mkdocstrings", "documentation", "docstring", "matlab"]
+license = {file = "LICENSE"}
+classifiers = [
+  # How mature is this project? Common values are
+  #   3 - Alpha
+  #   4 - Beta
+  #   5 - Production/Stable
+  "Development Status :: 3 - Alpha",
+
+  # Indicate who your project is intended for
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Documentation",
+
+  # Pick your license as you wish (see also "license" above)
+  "License :: OSI Approved :: MIT License",
+
+  # Specify the Python versions you support here.
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Documentation = "http://watermarkhu.nl/mkdocstrings-matlab/"
+Repository = "https://github.com/watermarkhu/mkdocstrings-matlab"
+Issues = "https://github.com/watermarkhu/mkdocstrings-matlab/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.rye]
+managed = true
+dev-dependencies = []
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mkdocstrings_handlers"]

mkdocstrings_matlab-0.2.1/submodules/mkdocstrings-matlab-r2024b/src/mkdocstrings_handlers/matlab_engine/__init__.py

@@ -0,0 +1,8 @@
+import matlab.engine
+from matlab.engine import MatlabExecutionError
+
+
+__all__ = ["MatlabEngine", "MatlabExecutionError"]
+
+
+MatlabEngine = matlab.engine.start_matlab

mkdocstrings_matlab-0.1.7/src/mkdocstrings_handlers/matlab/matlab/+docstring/+case/builtin.m

@@ -1,8 +0,0 @@
-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