mkdocstrings-matlab 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

mkdocstrings_handlers/matlab/__init__.py

@@ -1,5 +1,26 @@
 """MATLAB handler for mkdocstrings."""
 
 from mkdocstrings_handlers.matlab.handler import get_handler
+from _griffe.enumerations import DocstringSectionKind
+from _griffe.docstrings import numpy, google
 
 __all__ = ["get_handler"]
+
+
+# Add custom sections to the numpy and google docstring parsers
+extensions = {
+    "arguments": DocstringSectionKind.parameters,
+    "input arguments": DocstringSectionKind.parameters,
+    "outputs": DocstringSectionKind.returns,
+    "output arguments": DocstringSectionKind.returns,
+    "name value arguments": DocstringSectionKind.other_parameters,
+    "name-value arguments": DocstringSectionKind.other_parameters,
+    "name value pairs": DocstringSectionKind.other_parameters,
+    "name-value pairs": DocstringSectionKind.other_parameters,
+    "properties": DocstringSectionKind.attributes,
+    "namespaces": DocstringSectionKind.modules,
+    "packages": DocstringSectionKind.modules,
+}
+
+google._section_kind.update(extensions)
+numpy._section_kind.update(extensions)

mkdocstrings_handlers/matlab/collect.py

@@ -1,15 +1,17 @@
 from collections import defaultdict, deque
-from copy import deepcopy
+from copy import copy, deepcopy
 from pathlib import Path
 from typing import Mapping, Sequence
 
 from _griffe.collections import LinesCollection as GLC, ModulesCollection
 from _griffe.docstrings.models import (
+    DocstringSectionOtherParameters,
     DocstringSectionParameters,
     DocstringSectionReturns,
     DocstringParameter,
     DocstringReturn,
 )
+from _griffe.enumerations import DocstringSectionKind
 from _griffe.expressions import Expr
 
 from mkdocstrings_handlers.matlab.enums import ParameterKind
@@ -223,9 +225,24 @@ class PathCollection(ModulesCollection):
             model.docstring.parser = config.get("docstring_style", "google")
             model.docstring.parser_options = config.get("docstring_options", {})
 
+        # Patch docstring section titles
+        if model.docstring is not None:
+            for section in model.docstring.parsed:
+                match section.kind:
+                    case DocstringSectionKind.attributes:
+                        section.title = "Properties:"
+                    case DocstringSectionKind.modules:
+                        section.title = "Namespaces:"
+                    case DocstringSectionKind.parameters:
+                        section.title = "Input arguments:"
+                    case DocstringSectionKind.returns:
+                        section.title= "Output arguments:"
+                    case DocstringSectionKind.other_parameters:
+                        section.title = "Name-Value Arguments:"
+
         # Patch returns annotation
         # In _griffe.docstrings.<parser>.py the function _read_returns_section will enforce an annotation
-        # on the return parameter. This annotation is grabbed from the parent. For MATLAB is is invalid.
+        # on the return parameter. This annotation is grabbed from the parent. For MATLAB this is invalid.
         # Thus the return annotation needs to be patched back to a None.
         if (
             isinstance(model, Function)
@@ -244,31 +261,128 @@ class PathCollection(ModulesCollection):
                 if not isinstance(returns.annotation, Expr):
                     returns.annotation = None
 
+        # previous updates do not edit the model attributes persistently
+        # However, the following updates do edit the model attributes persistently
+        # such as adding new sections to the docstring or editing its members.abs
+        # Thus, we need to copy the model to avoid editing the original model
+        alias = copy(model)
+        alias.docstring = (
+            deepcopy(model.docstring) if model.docstring is not None else None
+        )
+        alias.members = {key: value for key, value in model.members.items()}
+        if isinstance(alias, Class):
+            alias._inherited_members = None
+
+        for name, member in getattr(alias, "members", {}).items():
+            alias.members[name] = self.update_model(member, config)
+
+        # Merge constructor docstring into class
+        if (
+            isinstance(alias, Class)
+            and config.get("merge_constructor_into_class", False)
+            and alias.name in alias.members
+            and alias.members[alias.name].docstring is not None
+        ):
+            constructor = alias.members.pop(alias.name)
+            if constructor.docstring is not None:
+                if alias.docstring is None:
+                    alias.docstring = Docstring("", parent=alias)
+
+                if config.get("merge_constructor_ignore_summary", False):
+                    alias.docstring._suffixes.extend(constructor.docstring.parsed[1:])
+                else:
+                    alias.docstring._suffixes.extend(constructor.docstring.parsed)
+
+        # Hide hidden members (methods and properties)
+        hidden_members = config.get("hidden_members", False)
+        if isinstance(hidden_members, bool):
+            filter_hidden = not hidden_members
+            show_hidden = []
+        else:
+            filter_hidden = True
+            show_hidden: list[str] = hidden_members
+        if isinstance(alias, Class) and filter_hidden:
+            alias.members = {
+                key: value
+                for key, value in alias.members.items()
+                if not getattr(value, "Hidden", False)
+                or (
+                    show_hidden
+                    and getattr(value, "Hidden", False)
+                    and key in show_hidden
+                )
+            }
+            alias._inherited_members = {
+                key: value
+                for key, value in alias.inherited_members.items()
+                if not getattr(value, "Hidden", False)
+                or (
+                    show_hidden
+                    and getattr(value, "Hidden", False)
+                    and key in show_hidden
+                )
+            }
+
+        # Hide private members (methods and properties)
+        private_members = config.get("private_members", False)
+        if isinstance(private_members, bool):
+            filter_private = not private_members
+            show_private = []
+        else:
+            filter_private = True
+            show_private: list[str] = private_members
+        if isinstance(alias, Class) and filter_private:
+            alias.members = {
+                key: value
+                for key, value in alias.members.items()
+                if not getattr(value, "Private", False)
+                or (
+                    show_private
+                    and getattr(value, "Private", False)
+                    and key in show_private
+                )
+            }
+            alias._inherited_members = {
+                key: value
+                for key, value in alias.inherited_members.items()
+                if not getattr(value, "Private", False)
+                or (
+                    show_private
+                    and getattr(value, "Private", False)
+                    and key in show_private
+                )
+            }
+
         # Create parameters and returns sections from argument blocks
         if (
-            isinstance(model, Function)
-            and model.docstring is not None
-            and config.get("create_from_argument_blocks", True)
+            isinstance(alias, Function)
+            and alias.docstring is not None
+            and config.get("parse_arguments", True)
+            and (
+                config.get("show_docstring_input_arguments", True)
+                or config.get("show_docstring_name_value_arguments", True)
+                or config.get("show_docstring_output_arguments", True)
+            )
         ):
             docstring_parameters = any(
                 isinstance(doc, DocstringSectionParameters)
-                for doc in model.docstring.parsed
+                for doc in alias.docstring.parsed
             )
             docstring_returns = any(
                 isinstance(doc, DocstringSectionReturns)
-                for doc in model.docstring.parsed
+                for doc in alias.docstring.parsed
             )
 
-            if not docstring_parameters and model.parameters:
+            if not docstring_parameters and alias.parameters:
                 arguments_parameters = any(
-                    param.docstring is not None for param in model.parameters
+                    param.docstring is not None for param in alias.parameters
                 )
             else:
                 arguments_parameters = False
 
-            if not docstring_returns and model.returns:
+            if not docstring_returns and alias.returns:
                 arguments_returns = any(
-                    ret.docstring is not None for ret in model.returns
+                    ret.docstring is not None for ret in alias.returns
                 )
             else:
                 arguments_returns = False
@@ -277,17 +391,23 @@ class PathCollection(ModulesCollection):
             document_returns = not docstring_returns and arguments_returns
 
             standard_parameters = [
-                param for param in model.parameters
+                param
+                for param in alias.parameters
                 if param.kind is not ParameterKind.keyword_only
             ]
 
             keyword_parameters = [
-                param for param in model.parameters
+                param
+                for param in alias.parameters
                 if param.kind is ParameterKind.keyword_only
             ]
 
-            if document_parameters and standard_parameters:
-                model.docstring._extra_sections.append(
+            if (
+                config.get("show_docstring_input_arguments", True)
+                and document_parameters
+                and standard_parameters
+            ):
+                alias.docstring._suffixes.append(
                     DocstringSectionParameters(
                         [
                             DocstringParameter(
@@ -305,10 +425,13 @@ class PathCollection(ModulesCollection):
                     )
                 )
 
-            if document_parameters and keyword_parameters:
-
-                model.docstring._extra_sections.append(
-                    DocstringSectionParameters(
+            if (
+                config.get("show_docstring_name_value_arguments", True)
+                and document_parameters
+                and keyword_parameters
+            ):
+                alias.docstring._suffixes.append(
+                    DocstringSectionOtherParameters(
                         [
                             DocstringParameter(
                                 name=param.name,
@@ -322,11 +445,11 @@ class PathCollection(ModulesCollection):
                             )
                             for param in keyword_parameters
                         ],
-                        title="Keyword Arguments:",
+                        title="Name-Value Arguments:",
                     )
                 )
 
-            if document_returns:
+            if config.get("show_docstring_output_arguments", True) and document_returns:
                 returns = DocstringSectionReturns(
                     [
                         DocstringReturn(
@@ -339,46 +462,30 @@ class PathCollection(ModulesCollection):
                             if param.docstring is not None
                             else "",
                         )
-                        for param in model.returns or []
+                        for param in alias.returns or []
                     ]
                 )
-                model.docstring._extra_sections.append(returns)
-
-        for member in getattr(model, "members", {}).values():
-            self.update_model(member, config)
-
-        if (
-            isinstance(model, Class)
-            and config.get("merge_constructor_into_class", False)
-            and model.name in model.members
-            and model.members[model.name].docstring is not None
-        ):
-            model = deepcopy(model)
-            constructor = model.members.pop(model.name)
-            if constructor.docstring is not None:
-                if model.docstring is None:
-                    model.docstring = Docstring("", parent=model)
-                model.docstring._extra_sections.extend(constructor.docstring.parsed)
+                alias.docstring._suffixes.append(returns)
 
+        # Add inheritance diagram to class docstring
         if (
-            isinstance(model, Class)
+            isinstance(alias, Class)
             and config.get("show_inheritance_diagram", False)
             and (
                 (
-                    model.docstring is not None
-                    and "Inheritance Diagram" not in model.docstring.parsed
+                    alias.docstring is not None
+                    and "Inheritance Diagram" not in alias.docstring.parsed
                 )
-                or model.docstring is None
+                or alias.docstring is None
             )
         ):
-            diagram = self.get_inheritance_diagram(model)
+            diagram = self.get_inheritance_diagram(alias)
             if diagram is not None:
-                model = deepcopy(model)
-                if model.docstring is None:
-                    model.docstring = Docstring("", parent=model)
-                model.docstring._extra_sections.append(diagram)
+                if alias.docstring is None:
+                    alias.docstring = Docstring("", parent=alias)
+                alias.docstring._prefixes.append(diagram)
 
-        return model
+        return alias
 
     def addpath(self, path: str | Path, to_end: bool = False, recursive: bool = False):
         """
@@ -469,7 +576,7 @@ class PathCollection(ModulesCollection):
 
         nodes_str = "\n".join(list(nodes))
         links_str = "\n".join(list(get_links(model)))
-        section = f"## Inheritance Diagram\n\n```mermaid\nflowchart TB\n{nodes_str}\n{links_str}\n```"
+        section = f"```mermaid\nflowchart TB\n{nodes_str}\n{links_str}\n```"
 
         return DocstringSectionText(section, title="Inheritance Diagram")
 
@@ -577,11 +684,7 @@ class LazyModel:
         if not isinstance(model, Classfolder):
             return None
         for member in path.iterdir():
-            if (
-                member.is_file()
-                and member.suffix == ".m"
-                and member != classfile
-            ):
+            if member.is_file() and member.suffix == ".m" and member != classfile:
                 if member.name == "Contents.m" and model.docstring is None:
                     contentsfile = self._collect_path(member)
                     model.docstring = contentsfile.docstring
@@ -618,14 +721,13 @@ class LazyModel:
         return model
 
     def _collect_readme_md(self, path, parent: MatlabMixin) -> Docstring | None:
-
         if (path / "README.md").exists():
             readme = path / "README.md"
         elif (path / "readme.md").exists():
             readme = path / "readme.md"
         else:
             return None
-        
+
         with open(readme, "r") as file:
             content = file.read()
-        return Docstring(content, parent=parent)
+        return Docstring(content, parent=parent)

mkdocstrings_handlers/matlab/handler.py

@@ -1,11 +1,13 @@
 from pathlib import Path
 from collections import ChainMap
 from markdown import Markdown
+from mkdocstrings.extension import PluginError
 from mkdocstrings.handlers.base import BaseHandler, CollectorItem, CollectionError
 from mkdocstrings_handlers.python import rendering
 from typing import Any, ClassVar, Mapping
 from pprint import pprint
 
+import re
 
 from mkdocstrings_handlers.matlab.collect import LinesCollection, PathCollection
 
@@ -23,7 +25,6 @@ class MatlabHandler(BaseHandler):
     """The fallback theme."""
     fallback_config: ClassVar[dict] = {
         "fallback": True,
-        "merge_constructor_into_class": True,
     }
     """The configuration used to collect item during autorefs fallback."""
     default_config: ClassVar[dict] = {
@@ -33,6 +34,7 @@ class MatlabHandler(BaseHandler):
         "show_source": True,
         # Heading options
         "heading_level": 2,
+        "parameter_headings": True,
         "show_root_heading": False,
         "show_root_toc_entry": True,
         "show_root_full_path": True,
@@ -42,37 +44,37 @@ class MatlabHandler(BaseHandler):
         "show_symbol_type_heading": False,
         "show_symbol_type_toc": False,
         # Member options
-        "inherited_members": False,
         "members": None,
-        "members_order": rendering.Order.alphabetical,  # TODO broken
-        "filters": [],
-        "group_by_category": True,  # TODO broken
-        "summary": False,  # TODO broken
+        "hidden_members": False,
+        "private_members": False,
+        "inherited_members": False,
+        "members_order": rendering.Order.alphabetical.value,
+        "filters": ["!^delete$|^disp$"],
+        "group_by_category": True,
+        "summary": False,
         "show_labels": True,
         # Docstring options
         "docstring_style": "google",
         "docstring_options": {},
         "docstring_section_style": "table",
-        "create_from_argument_blocks": False,
-        "merge_constructor_into_class": True,
+        "parse_arguments": False,
+        "merge_constructor_into_class": False,
+        "merge_constructor_ignore_summary": False,
         "show_if_no_docstring": False,
-        "show_docstring_attributes": True,
+        "show_docstring_propeties": True,
         "show_docstring_functions": True,
         "show_docstring_classes": True,
-        "show_docstring_modules": True,  # TODO should be replaced with namespaces
+        "show_docstring_namespaces": True,
         "show_docstring_description": True,
         "show_docstring_examples": True,
-        "show_docstring_other_parameters": True,  # TODO should be name value pairs
-        "show_docstring_parameters": True,
-        "show_docstring_raises": True,  # TODO need to additional parsing for this
-        "show_docstring_returns": True,
-        "show_docstring_warns": True,  # TODO need to additional parsing for this
+        "show_docstring_input_arguments": True,
+        "show_docstring_name_value_arguments": True,
+        "show_docstring_output_arguments": True,
         # Signature options
-        "annotations_path": "brief",
-        "line_length": 60,
         "show_signature": True,
         "show_signature_annotations": False,
         "separate_signature": False,
+        "signature_crossrefs": False,
     }
     """Default handler configuration.
 
@@ -84,6 +86,7 @@ class MatlabHandler(BaseHandler):
 
     Attributes: 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`.
@@ -95,50 +98,52 @@ class MatlabHandler(BaseHandler):
         show_symbol_type_toc (bool): Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr). Default: `False`.
 
     Attributes: Members options:
-        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 (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.
             The `members` option takes precedence over `filters` (filters will still be applied recursively
-            to lower members in the hierarchy). Default: `["!^_[^_]"]`.
-        group_by_category (bool): Group the object's children by categories: attributes, classes, functions, and modules. Default: `True`.
-        summary (bool | dict[str, bool]): Whether to render summaries of modules, classes, functions (methods) and attributes.
+            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`.
+        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`.
 
     Attributes: Docstrings options:
         docstring_style (str): The docstring style to use: `google`, `numpy`, `sphinx`, or `None`. Default: `"google"`.
         docstring_options (dict): The options for the docstring parser. See [docstring parsers](https://mkdocstrings.github.io/griffe/reference/docstrings/) 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`.
-        create_from_argument_blocks (bool): Whether to create sections for inputs and output arguments based on argument validation blocks. Default: `False`.
-        relative_crossrefs (bool): Whether to enable the relative crossref syntax. Default: `False`.
-        scoped_crossrefs (bool): Whether to enable the scoped crossref ability. 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_attributes (bool): Whether to display the "Attributes" section in the object's docstring. Default: `True`.
+        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_modules (bool): Whether to display the "Modules" 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_other_parameters (bool): Whether to display the "Other Parameters" section in the object's docstring. Default: `True`.
-        show_docstring_parameters (bool): Whether to display the "Parameters" section in the object's docstring. Default: `True`.
-        show_docstring_raises (bool): Whether to display the "Raises" section in the object's docstring. Default: `True`.
-        show_docstring_returns (bool): Whether to display the "Returns" section in the object's docstring. Default: `True`.
-        show_docstring_warns (bool): Whether to display the "Warns" 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`.
 
     Attributes: Signatures/annotations options:
-        annotations_path (str): The verbosity for annotations path: `brief` (recommended), or `source` (as written in the source). Default: `"brief"`.
-        line_length (int): Maximum line length when formatting code/signatures. Default: `60`.
         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`.
     """
 
     def __init__(
@@ -200,6 +205,77 @@ class MatlabHandler(BaseHandler):
 
         heading_level = final_config["heading_level"]
 
+        try:
+            final_config["members_order"] = rendering.Order(
+                final_config["members_order"]
+            )
+        except ValueError as error:
+            choices = "', '".join(item.value for item in rendering.Order)
+            raise PluginError(
+                f"Unknown members_order '{final_config['members_order']}', choose between '{choices}'.",
+            ) from error
+
+        if final_config["filters"]:
+            final_config["filters"] = [
+                (re.compile(filtr.lstrip("!")), filtr.startswith("!"))
+                for filtr in final_config["filters"]
+            ]
+
+        summary = final_config["summary"]
+        if summary is True:
+            final_config["summary"] = {
+                "attributes": True,
+                "functions": True,
+                "classes": True,
+                "modules": True,
+            }
+        elif summary is False:
+            final_config["summary"] = {
+                "attributes": False,
+                "functions": False,
+                "classes": False,
+                "modules": False,
+            }
+        else:
+            final_config["summary"] = {
+                "attributes": summary.get(
+                    "properties", False
+                ),  # Map properties (MATLAB) to attributes (Python)
+                "functions": summary.get("functions", False),
+                "classes": summary.get("classes", False),
+                "modules": summary.get(
+                    "namespaces", False
+                ),  # Map namespaces (MATLAB) to modules (Python)
+            }
+
+        # Map docstring options
+        final_config["show_docstring_attributes"] = config.get(
+            "show_docstring_properties", True
+        )
+        final_config["show_docstring_modules"] = config.get(
+            "show_docstring_namespaces", True
+        )
+        final_config["show_docstring_parameters"] = config.get(
+            "show_docstring_input_arguments", True
+        )
+        final_config["show_docstring_other_parameters"] = config.get(
+            "show_docstring_name_value_arguments", True
+        )
+        final_config["show_docstring_returns"] = config.get(
+            "show_docstring_output_arguments", True
+        )
+
+        # These settings must be present to avoid errors
+        for setting in [
+            "merge_init_into_class",
+            "show_docstring_raises",
+            "show_docstring_receives",
+            "show_docstring_yields",
+            "show_docstring_warns",
+        ]:
+            final_config[setting] = False
+        final_config["line_length"] = 88
+
         return template.render(
             **{
                 "config": final_config,
@@ -229,12 +305,13 @@ class MatlabHandler(BaseHandler):
         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["stash_crossref"] = rendering.do_stash_crossref
         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.globals["AutorefsHook"] = rendering.AutorefsHook
         self.env.tests["existing_template"] = (
             lambda template_name: template_name in self.env.list_templates()
         )

mkdocstrings_handlers/matlab/models.py

@@ -2,6 +2,7 @@ from typing import Any, TYPE_CHECKING, Callable
 from functools import cached_property
 from pathlib import Path
 from griffe import (
+    Alias,
     Attribute,
     Function as GriffeFunction,
     Class as GriffeClass,
@@ -45,7 +46,7 @@ class Docstring(GriffeDocstring):
     that can be added to the parsed docstring.
 
     Attributes:
-        _extra_sections (list[DocstringSection]): A list to store additional docstring sections.
+        _suffixes (list[DocstringSection]): A list to store additional docstring sections.
 
     Methods:
         parsed: Returns the parsed docstring sections combined with extra sections.
@@ -61,7 +62,8 @@ class Docstring(GriffeDocstring):
             **kwargs (Any): Arbitrary keyword arguments.
         """
         super().__init__(*args, **kwargs)
-        self._extra_sections: list[DocstringSection] = []
+        self._prefixes: list[DocstringSection] = []
+        self._suffixes: list[DocstringSection] = []
 
     @property
     def parsed(self) -> list[DocstringSection]:
@@ -71,7 +73,7 @@ class Docstring(GriffeDocstring):
         Returns:
             list[DocstringSection]: The combined list of parsed and extra docstring sections.
         """
-        return self._parsed + self._extra_sections
+        return self._prefixes + self._parsed + self._suffixes
 
     @cached_property
     def _parsed(self) -> list[DocstringSection]:
@@ -318,9 +320,10 @@ class Class(MatlabMixin, PathMixin, GriffeClass, MatlabObject):
         **kwargs: Any,
     ) -> None:
         super().__init__(*args, **kwargs)
-        self.abstract: bool = Abstract
-        self.hidden: bool = Hidden
-        self.sealed: bool = Sealed
+        self.Abstract: bool = Abstract
+        self.Hidden: bool = Hidden
+        self.Sealed: bool = Sealed
+        self._inherited_members: dict[str, MatlabObject] | None = None
 
     @property
     def parameters(self) -> Parameters:
@@ -350,6 +353,8 @@ class Class(MatlabMixin, PathMixin, GriffeClass, MatlabObject):
         Returns:
             dict[str, MatlabObject]: A dictionary where the keys are member names and the values are the corresponding MatlabObject instances.
         """
+        if self._inherited_members is not None:
+            return self._inherited_members
 
         inherited_members = {}
         for base in reversed(self.bases):
@@ -364,28 +369,28 @@ class Class(MatlabMixin, PathMixin, GriffeClass, MatlabObject):
 
             for name, member in model.members.items():
                 if name not in self.members:
-                    inherited_members[name] = member
+                    inherited_members[name] = Alias(
+                        name, target=member, parent=self, inherited=True
+                    )
+
+        self._inherited_members = inherited_members
         return inherited_members
 
     @property
     def labels(self) -> set[str]:
         labels = set()
-        if self.abstract:
-            labels.add("abstract")
-        if self.hidden:
-            labels.add("hidden")
-        if self.sealed:
-            labels.add("sealed")
+        if self.Abstract:
+            labels.add("Abstract")
+        if self.Hidden:
+            labels.add("Hidden")
+        if self.Sealed:
+            labels.add("Sealed")
         return labels
 
     @labels.setter
     def labels(self, *args):
         pass
 
-    @property
-    def is_private(self) -> bool:
-        return self.hidden
-
     @property
     def canonical_path(self) -> str:
         if isinstance(self.parent, Classfolder):
@@ -416,54 +421,61 @@ class Property(MatlabMixin, Attribute, MatlabObject):
         SetObservable: bool = False,
         Transient: bool = False,
         WeakHandle: bool = False,
+        Access: AccessEnum = AccessEnum.public,
         GetAccess: AccessEnum = AccessEnum.public,
         SetAccess: AccessEnum = AccessEnum.public,
         **kwargs: Any,
     ) -> None:
         super().__init__(*args, **kwargs)
-        self.abort_set: bool = AbortSet
-        self.abstract: bool = Abstract
-        self.constant: bool = Constant
-        self.dependent: bool = Dependent
-        self.get_observable: bool = GetObservable
-        self.hidden: bool = Hidden
-        self.non_copyable: bool = NonCopyable
-        self.set_observable: bool = SetObservable
-        self.transient: bool = Transient
-        self.weak_handle: bool = WeakHandle
-        self.get_access: AccessEnum = GetAccess
-        self.set_access: AccessEnum = SetAccess
+        self.AbortSet: bool = AbortSet
+        self.Abstract: bool = Abstract
+        self.Constant: bool = Constant
+        self.Dependent: bool = Dependent
+        self.GetObservable: bool = GetObservable
+        self.Hidden: bool = Hidden
+        self.NonCopyable: bool = NonCopyable
+        self.SetObservable: bool = SetObservable
+        self.Transient: bool = Transient
+        self.WeakHandle: bool = WeakHandle
+        self.Access = Access
+        self.GetAccess: AccessEnum = GetAccess
+        self.SetAccess: AccessEnum = SetAccess
         self.getter: Function | None = None
 
     @property
-    def is_private(self) -> bool:
-        set_public = (
-            self.set_access == AccessEnum.public
-            or self.set_access == AccessEnum.immutable
+    def Private(self) -> bool:
+        private = self.Access != AccessEnum.public
+        set_private = (
+            self.SetAccess != AccessEnum.public
+            and self.SetAccess != AccessEnum.immutable
         )
-        get_public = self.get_access == AccessEnum.public
-        return (set_public or get_public) and not self.hidden
+        get_private = self.GetAccess != AccessEnum.public
+        return private or set_private or get_private
+
+    @property
+    def is_private(self) -> bool:
+        return self.Private or self.Hidden
 
     @property
     def labels(self) -> set[str]:
         labels = set()
         for attr in [
-            "abort_set",
-            "abstract",
-            "constant",
-            "dependent",
-            "get_observable",
-            "hidden",
-            "non_copyable",
-            "set_observable",
-            "transient",
-            "weak_handle",
+            "AbortSet",
+            "Abstract",
+            "Constant",
+            "Dependent",
+            "GetObservable",
+            "Hidden",
+            "NonCopyable",
+            "SetObservable",
+            "Transient",
+            "WeakHandle",
         ]:
             if getattr(self, attr):
                 labels.add(attr)
-        for attr in ["get_access", "set_access"]:
+        for attr in ["Access", "GetAccess", "SetAccess"]:
             if getattr(self, attr) != AccessEnum.public:
-                labels.add(f"{attr}={str(getattr(self, attr))}")
+                labels.add(f"{attr}={getattr(self, attr).value}")
         return labels
 
     @labels.setter
@@ -514,27 +526,30 @@ class Function(MatlabMixin, PathMixin, GriffeFunction, MatlabObject):
         super().__init__(*args, **kwargs)
         self.parameters: Parameters = Parameters()
         self.returns: Parameters | None = returns
-        self.access: AccessEnum = Access
-        self.static: bool = Static
-        self.abstract: bool = Abstract
-        self.sealed: bool = Sealed
-        self.hidden: bool = Hidden
+        self.Access: AccessEnum = Access
+        self.Static: bool = Static
+        self.Abstract: bool = Abstract
+        self.Sealed: bool = Sealed
+        self.Hidden: bool = Hidden
         self._is_setter: bool = setter
         self._is_getter: bool = getter
 
+    @property
+    def Private(self) -> bool:
+        return self.Access != AccessEnum.public and self.Access != AccessEnum.immutable
+
     @property
     def is_private(self) -> bool:
-        public = self.access == AccessEnum.public or self.access == AccessEnum.immutable
-        return public and not self.hidden
+        return self.Private or self.Hidden
 
     @property
     def labels(self) -> set[str]:
         labels = set()
-        for attr in ["abstract", "hidden", "sealed", "static"]:
+        for attr in ["Abstract", "Hidden", "Sealed", "Static"]:
             if getattr(self, attr):
                 labels.add(attr)
-        if self.access != AccessEnum.public:
-            labels.add(f"access={str(self.access)}")
+        if self.Access != AccessEnum.public:
+            labels.add(f"Access={self.Access.value}")
         return labels
 
     @labels.setter
@@ -561,4 +576,8 @@ class Namespace(MatlabMixin, PathMixin, Module, MatlabObject):
 
     @property
     def is_internal(self) -> bool:
-        return any(part == "+internal" for part in self.filepath.parts) if self.filepath else False
+        return (
+            any(part == "+internal" for part in self.filepath.parts)
+            if self.filepath
+            else False
+        )

mkdocstrings_handlers/matlab/treesitter.py

@@ -105,9 +105,9 @@ CLASS_QUERY = LANGUAGE.query("""("classdef" .
     (attributes
         (attribute) @attributes
     )? .
-    (identifier) @name ?
+    (identifier) @name .
     (superclasses
-        (property_name)+ @bases             
+        (property_name) @bases             
     )? .
     (comment)* @docstring .
     ("\\n")? .
@@ -316,7 +316,7 @@ class FileParser(object):
                     "WeakHandle",
                 ]:
                     property_kwargs[key] = value
-                elif key in ["GetAccess", "SetAccess"]:
+                elif key in ["Access", "GetAccess", "SetAccess"]:
                     if value in ["public", "protected", "private", "immutable"]:
                         property_kwargs[key] = AccessEnum(value)
                     else:
@@ -332,6 +332,7 @@ class FileParser(object):
                         property_captures.get("comment", None)
                     ),
                     parent=model,
+                    **property_kwargs,
                 )
                 model.members[prop.name] = prop
 
@@ -351,7 +352,7 @@ class FileParser(object):
                     "Static",
                 ]:
                     method_kwargs[key] = value
-                elif key in ["GetAccess", "SetAccess"]:
+                elif key == "Access":
                     if value in ["public", "protected", "private", "immutable"]:
                         method_kwargs[key] = AccessEnum(value)
                     else:
@@ -362,7 +363,7 @@ class FileParser(object):
                 )
                 if (
                     method.name != self.filepath.stem
-                    and not method.static
+                    and not method.Static
                     and method.parameters
                 ):
                     # Remove self from first method argument

{mkdocstrings_matlab-0.3.2.dist-info → mkdocstrings_matlab-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-matlab
-Version: 0.3.2
+Version: 0.4.0
 Summary: A MATLAB handler for mkdocstrings
 Author-email: Mark Hu <watermarkhu@gmail.com>
 License: ISC
@@ -23,8 +23,9 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: charset-normalizer>=3.3.2
 Requires-Dist: griffe>=1.5.1
-Requires-Dist: mkdocs>=1.6.0
-Requires-Dist: mkdocstrings[python]>=0.18
+Requires-Dist: mkdocs==1.6.1
+Requires-Dist: mkdocstrings-python==1.13.0
+Requires-Dist: mkdocstrings==0.27.0
 Requires-Dist: tree-sitter-matlab>=1.0.2
 Requires-Dist: tree-sitter>=0.23.2
 Description-Content-Type: text/markdown
@@ -36,7 +37,7 @@ Description-Content-Type: text/markdown
 
 ---
 
-<p align="center"><img src="logo.png"></p>
+<p align="center"><img src="logo.svg"></p>
 
 The MATLAB handler uses [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) and its [MATLAB parser](https://github.com/acristoffers/tree-sitter-matlab) to collect documentation from MATLAB source code. Via the python bindings the Abstract Syntax Tree (AST) of the source code is traversed to extract useful information. The imported objected are imported as custom [Griffe](https://mkdocstrings.github.io/griffe/) objects and mocked for the [python handler](https://mkdocstrings.github.io/python/). 
 

mkdocstrings_matlab-0.4.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+mkdocs_material_matlab/__init__.py,sha256=9pmrwWbkIyr0T7qvADbsz3OR5bB3rWb231e6JSnwA7o,106
+mkdocs_material_matlab/mkdocs_material_matlab.py,sha256=s7vI1lv6hD8s7kDHWBfYKgN6EcldyUstGYJ45sA-VWY,850
+mkdocs_material_matlab/css/style.css,sha256=iVTPIKljgvK899jEQylD7yu9yjKfrVE_4GLaITjhk4g,132
+mkdocstrings_handlers/matlab/__init__.py,sha256=7UCCosKn8S38xgJQQy9_1P2oMyPVsTeDkcLPVIoDneU,1000
+mkdocstrings_handlers/matlab/collect.py,sha256=JAcYih8LMU9jDgxuyqR86p6zdp5qYJNxVnE3x9c529U,27440
+mkdocstrings_handlers/matlab/enums.py,sha256=lr3wLlhPxyBym3O7Rt0cLUZYqPCz6wQ2PYBibLKLTek,982
+mkdocstrings_handlers/matlab/handler.py,sha256=Peg4DJsulnJINpdYXMid9dezuVts_P85cOUlowCw7T4,18343
+mkdocstrings_handlers/matlab/models.py,sha256=YmPE9NKsPJ4GBp6es--0yH6uH8BZLPC8xMOh1QHCmY4,18109
+mkdocstrings_handlers/matlab/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkdocstrings_handlers/matlab/treesitter.py,sha256=e2rfMPFaprJ6XEPH8xk2i-DKBOY_9UNWFQWPX2R7U98,21756
+mkdocstrings_matlab-0.4.0.dist-info/METADATA,sha256=Q98qVYeK2T1zPs6eToAsOUhif0g21MKv447vcle3-VQ,4134
+mkdocstrings_matlab-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mkdocstrings_matlab-0.4.0.dist-info/entry_points.txt,sha256=qUZFuB2TKh7KPlg4dR2npfbNgNExw6O6j1vF276PtPw,92
+mkdocstrings_matlab-0.4.0.dist-info/licenses/LICENSE,sha256=z5Ee0lckFL6K9LhLKftDu0JDl2Uie24Po20IclVk2SI,743
+mkdocstrings_matlab-0.4.0.dist-info/RECORD,,

mkdocstrings_matlab-0.3.2.dist-info/RECORD

@@ -1,15 +0,0 @@
-mkdocs_material_matlab/__init__.py,sha256=9pmrwWbkIyr0T7qvADbsz3OR5bB3rWb231e6JSnwA7o,106
-mkdocs_material_matlab/mkdocs_material_matlab.py,sha256=s7vI1lv6hD8s7kDHWBfYKgN6EcldyUstGYJ45sA-VWY,850
-mkdocs_material_matlab/css/style.css,sha256=iVTPIKljgvK899jEQylD7yu9yjKfrVE_4GLaITjhk4g,132
-mkdocstrings_handlers/matlab/__init__.py,sha256=laA2bEP5rxdIWBLmfLiKKu7ChZ_HzCe-VeRvxmUTqww,128
-mkdocstrings_handlers/matlab/collect.py,sha256=9DKuE5Q6kXcNm6coQZnmtTNRzMNIeILlljMd1GgVEKk,23035
-mkdocstrings_handlers/matlab/enums.py,sha256=lr3wLlhPxyBym3O7Rt0cLUZYqPCz6wQ2PYBibLKLTek,982
-mkdocstrings_handlers/matlab/handler.py,sha256=KmQuCuaoS-K8HR2peS4LfvBUaJT4a8-428-3ZiHRdYY,15427
-mkdocstrings_handlers/matlab/models.py,sha256=y4ozShL4edxKKgb6jqBAfSI8Z9MEygSbEDnTDfBnRtk,17513
-mkdocstrings_handlers/matlab/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mkdocstrings_handlers/matlab/treesitter.py,sha256=dW4RcSep4A0L505WbAE9PGL2sTqizX7nhXLwQqbJh8Y,21726
-mkdocstrings_matlab-0.3.2.dist-info/METADATA,sha256=c1mVS2_ocxD-sPdaTEWYauALHXUHoF1qVtnxdLl1k0M,4097
-mkdocstrings_matlab-0.3.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mkdocstrings_matlab-0.3.2.dist-info/entry_points.txt,sha256=qUZFuB2TKh7KPlg4dR2npfbNgNExw6O6j1vF276PtPw,92
-mkdocstrings_matlab-0.3.2.dist-info/licenses/LICENSE,sha256=z5Ee0lckFL6K9LhLKftDu0JDl2Uie24Po20IclVk2SI,743
-mkdocstrings_matlab-0.3.2.dist-info/RECORD,,