mkdocstrings-matlab 0.8.2__py3-none-any.whl → 0.9.1__py3-none-any.whl

mkdocstrings_handlers/matlab/collect.py

@@ -3,7 +3,7 @@
 from collections import defaultdict, deque
 from copy import copy, deepcopy
 from pathlib import Path
-from typing import Mapping, Sequence, Callable, TypeVar
+from typing import Any, Mapping, Sequence, Callable, TypeVar
 
 from _griffe.collections import LinesCollection as GLC, ModulesCollection
 from _griffe.docstrings.models import (
@@ -716,9 +716,9 @@ class LazyModel:
             parent = None
         return parent
 
-    def _collect_path(self, path: Path) -> MatlabMixin:
+    def _collect_path(self, path: Path, **kwargs: Any) -> MatlabMixin:
         file = FileParser(path)
-        model = file.parse(path_collection=self._path_collection)
+        model = file.parse(path_collection=self._path_collection, **kwargs)
         self._lines_collection[path] = file.content.split("\n")
         return model
 

mkdocstrings_handlers/matlab/enums.py

@@ -1,4 +1,23 @@
 from enum import Enum
+from _griffe.enumerations import Kind as GriffeKind
+
+
+class Kind(str, Enum):
+    """
+    An enumeration representing different kinds of MATLAB code elements.
+    This enumeration is a subclass of the Griffe `Kind` enumeration, and extends it with additional values.
+    """
+    MODULE = "module"
+    """Modules."""
+    CLASS = "class"
+    """Classes."""
+    FUNCTION = "function"
+    """Functions and methods."""
+    ATTRIBUTE = "attribute"
+    """Attributes and properties."""
+    ALIAS = "alias"
+    """Aliases (imported objects)."""
+    SCRIPT = "script"
 
 
 class ParameterKind(str, Enum):

mkdocstrings_handlers/matlab/handler.py

@@ -193,7 +193,7 @@ class MatlabHandler(BaseHandler):
             config_path = None
             full_paths = []
         else:
-            config_path = Path(config_file_path).parent
+            config_path = Path(config_file_path).resolve().parent
             full_paths = [(config_path / path).resolve() for path in paths]
 
         if pathIds := [str(path) for path in full_paths if not path.is_dir()]:

mkdocstrings_handlers/matlab/models.py

@@ -17,7 +17,7 @@ from griffe import (
     Parameter as GriffeParameter,
 )
 
-from mkdocstrings_handlers.matlab.enums import AccessEnum, ParameterKind
+from mkdocstrings_handlers.matlab.enums import Kind, AccessEnum, ParameterKind
 
 if TYPE_CHECKING:
     from mkdocstrings_handlers.matlab.collect import PathCollection
@@ -151,6 +151,14 @@ class MatlabObject(Object):
     def namespaces(self) -> dict[str, "Namespace"]:
         return {}
 
+    @property
+    def scripts(self) -> dict[str, "Script"]:
+        return {name: member for name, member in self.all_members.items() if member.kind is Kind.SCRIPT} # type: ignore[misc]
+
+    @property
+    def is_script(self) -> bool:
+        return False
+    
     @property
     def is_namespace(self) -> bool:
         return False
@@ -280,9 +288,15 @@ class Script(MatlabMixin, PathMixin, MatlabObject):
     This class inherits from `PathMixin` and `MatlabObject` to provide
     functionality specific to MATLAB scripts.
     """
+    kind = Kind.SCRIPT # type: ignore
 
-    pass
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.extra["mkdocstrings"] = {"template": "script.html.jinja"}
 
+    @property
+    def is_script(self) -> bool:
+        return True
 
 class Class(MatlabMixin, PathMixin, GriffeClass, MatlabObject):
     """
@@ -442,13 +456,9 @@ class Property(MatlabMixin, Attribute, MatlabObject):
     @property
     def Private(self) -> bool:
         private = self.Access != AccessEnum.public
-        set_private = (
-            self.SetAccess != AccessEnum.public
-            and self.SetAccess != AccessEnum.immutable
-        )
         get_private = self.GetAccess != AccessEnum.public
-        return private or set_private or get_private
-
+        return private or get_private
+    
     @property
     def is_private(self) -> bool:
         return self.Private or self.Hidden

mkdocstrings_handlers/matlab/templates/material/children.html.jinja

@@ -99,6 +99,27 @@ Context:
           {% endif %}
         {% endwith %}
 
+        {% if obj.is_module %}
+          {% with scripts = obj.scripts|filter_objects(
+              filters=config.filters,
+              members_list=members_list,
+              keep_no_docstrings=config.show_if_no_docstring,
+            ) %}
+            {% if scripts %}
+              {% if config.show_category_heading %}
+                {% filter heading(heading_level, id=html_id ~ "-scripts") %}Scripts{% endfilter %}
+              {% endif %}
+              {% with heading_level = heading_level + extra_level %}
+                {% for script in scripts|order_members(config.members_order.alphabetical, members_list) %}
+                  {% if members_list is not none or (not script.is_alias or script.is_public) %}
+                    {% include script|get_template with context %}
+                  {% endif %}
+                {% endfor %}
+              {% endwith %}
+            {% endif %}
+          {% endwith %}
+        {% endif %}
+
         {% if config.show_subnamespaces or obj.is_folder %}
           {% with modules = obj.modules|filter_objects(
               filters=config.filters,

mkdocstrings_handlers/matlab/templates/material/script.html.jinja

@@ -0,0 +1,137 @@
+{#- Template for MATLAB scripts.
+
+This template renders a MATLAB script.
+
+Context:
+  script (mkdocstrings_handlers.matlab.models.Script): The Script to render.
+  root (bool): Whether this is the root object, injected with `:::` in a Markdown page.
+  heading_level (int): The HTML heading level to use.
+  config (dict): The configuration options.
+-#}
+
+{% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
+  {{ log.debug("Rendering " + script.path) }}
+{% endblock logs %}
+
+<div class="doc doc-object doc-function">
+  {% with obj = script, html_id = script.path %}
+
+    {% if root %}
+      {% set show_full_path = config.show_root_full_path %}
+      {% set root_members = True %}
+    {% elif root_members %}
+      {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+      {% set root_members = False %}
+    {% else %}
+      {% set show_full_path = config.show_object_full_path %}
+    {% endif %}
+
+    {% set script_name = script.path if show_full_path else script.name %}
+
+    {% if not root or config.show_root_heading %}
+      {% filter heading(
+          heading_level,
+          role="function",
+          id=html_id,
+          class="doc doc-heading",
+          toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-script"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + script.name,
+        ) %}
+
+        {% block heading scoped %}
+          {#- Heading block.
+          
+          This block renders the heading for the function.
+          -#}
+          {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-script"></code>{% endif %}
+          {% if config.separate_signature %}
+            <span class="doc doc-object-name doc-function-name">{{ script_name }}</span>
+          {% else %}
+            {%+ filter highlight(language="matlab", inline=True) %}
+              {{ script_name }}
+            {% endfilter %}
+          {% endif %}
+        {% endblock heading %}
+
+        {% block labels scoped %}
+          {#- Labels block.
+          
+          This block renders the labels for the script.
+          -#}
+          {% with labels = script.labels %}
+            {% include "labels"|get_template with context %}
+          {% endwith %}
+        {% endblock labels %}
+
+      {% endfilter %}
+
+      {% block signature scoped %}
+        {#- Signature block.
+        
+        This block renders the signature for the script.
+        -#}
+        {% if config.separate_signature %}
+          {% filter format_signature(script, config.line_length, crossrefs=config.signature_crossrefs) %}
+            {{ script.name }}
+          {% endfilter %}
+        {% endif %}
+      {% endblock signature %}
+
+    {% else %}
+
+      {% if config.show_root_toc_entry %}
+        {% filter heading(heading_level,
+            role="function",
+            id=html_id,
+            toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-script"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + script.name,
+            hidden=True,
+          ) %}
+        {% endfilter %}
+      {% endif %}
+      {% set heading_level = heading_level - 1 %}
+    {% endif %}
+
+    <div class="doc doc-contents {% if root %}first{% endif %}">
+      {% block contents scoped %}
+        {#- Contents block.
+        
+        This block renders the contents of the script.
+        It contains other blocks that users can override.
+        Overriding the contents block allows to rearrange the order of the blocks.
+        -#}
+        {% block docstring scoped %}
+          {#- Docstring block.
+          
+          This block renders the docstring for the script.
+          -#}
+          {% with docstring_sections = script.docstring.parsed %}
+            {% include "docstring"|get_template with context %}
+          {% endwith %}
+        {% endblock docstring %}
+
+        {% block source scoped %}
+          {#- Source block.
+          
+          This block renders the source code for the script.
+          -#}
+          {% if config.show_source and script.source %}
+            <details class="quote">
+              <summary>{{ lang.t("Source code in") }} <code>
+                {%- if script.relative_filepath.is_absolute() -%}
+                  {{ script.relative_package_filepath }}
+                {%- else -%}
+                  {{ script.relative_filepath }}
+                {%- endif -%}
+              </code></summary>
+              {{ script.source|highlight(language="python", linestart=script.lineno or 0, linenums=True) }}
+            </details>
+          {% endif %}
+        {% endblock source %}
+      {% endblock contents %}
+    </div>
+
+  {% endwith %}
+</div>

mkdocstrings_handlers/matlab/templates/material/style.css

@@ -24,3 +24,12 @@ code.doc-symbol-property {
 code.doc-symbol-property::after {
   content: "prop";
 }
+
+code.doc-symbol-script {
+  color: #d0bf3d;
+  background-color: #96862f27;
+}
+
+code.doc-symbol-script::after {
+  content: "script";
+}

mkdocstrings_handlers/matlab/treesitter.py

@@ -46,7 +46,7 @@ FUNCTION_QUERY = LANGUAGE.query("""(function_definition .
         [
             (identifier) @output
             (multioutput_variable .
-                ((identifier) @output (",")?)+
+                ((identifier) @output (",")?)*
             )
         ]
     )? .
@@ -68,6 +68,7 @@ ARGUMENTS_QUERY = LANGUAGE.query("""(arguments_statement .
     (attributes
         (identifier) @attributes
     )? .
+    (comment)? .
     ("\\n")? .
     (property)+ @arguments
 )""")
@@ -165,7 +166,7 @@ def _dedent(lines: list[str]) -> list[str]:
         list[str]: A list of strings with the common leading whitespace removed from each line.
     """
     indents = [len(line) - len(line.lstrip()) for line in lines if line.strip()]
-    indent = min(indents)
+    indent = min(indents) if indents else 0
     if indent == 0:
         return lines
     else:
@@ -208,7 +209,7 @@ class FileParser(object):
         """
         return self._content.decode(self.encoding)
 
-    def parse(self, **kwargs) -> MatlabMixin:
+    def parse(self, **kwargs: Any) -> MatlabMixin:
         """
         Parse the content of the file and return a MatlabMixin.
 
@@ -246,7 +247,7 @@ class FileParser(object):
 
         return model
 
-    def _parse_class(self, node: Node, **kwargs) -> Class:
+    def _parse_class(self, node: Node, **kwargs: Any) -> Class:
         """
         Parse a class node and return a Class or Classfolder model.
 
@@ -412,7 +413,7 @@ class FileParser(object):
 
         return (key, value)
 
-    def _parse_function(self, node: Node, method: bool = False, **kwargs) -> Function:
+    def _parse_function(self, node: Node, method: bool = False, **kwargs: Any) -> Function:
         """
         Parse a function node and return a Function model.
 
@@ -592,6 +593,12 @@ class FileParser(object):
         if nodes is None:
             return None
         elif isinstance(nodes, list):
+
+            # Ensure that if there is a gap between subsequent comment nodes, only the first block is considered
+            if gaps := (end.start_point.row - start.end_point.row for (start, end) in zip(nodes[:-1], nodes[1:])):
+                first_gap_index = next((i for i, gap in enumerate(gaps) if gap > 1), None) 
+                nodes = nodes[:first_gap_index+1] if first_gap_index is not None else nodes
+
             lineno = nodes[0].range.start_point.row + 1
             endlineno = nodes[-1].range.end_point.row + 1
             lines = iter(

{mkdocstrings_matlab-0.8.2.dist-info → mkdocstrings_matlab-0.9.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-matlab
-Version: 0.8.2
+Version: 0.9.1
 Summary: A MATLAB handler for mkdocstrings
 Author-email: Mark Hu <watermarkhu@gmail.com>
 License: MIT

{mkdocstrings_matlab-0.8.2.dist-info → mkdocstrings_matlab-0.9.1.dist-info}/RECORD

@@ -1,21 +1,22 @@
 mkdocstrings_handlers/matlab/__init__.py,sha256=w5R9cGtqeJF0GUP_Jc_ad8FnS4FpbutnmHvzVRlohPM,1124
-mkdocstrings_handlers/matlab/collect.py,sha256=a2ZLBpSmkfwc7uG63dnV36Y7gvnrwvmFK7Gihggn2hc,29647
-mkdocstrings_handlers/matlab/enums.py,sha256=lr3wLlhPxyBym3O7Rt0cLUZYqPCz6wQ2PYBibLKLTek,982
-mkdocstrings_handlers/matlab/handler.py,sha256=kHyBrHTvZJBXVgondNcbjyeRna0pMmfCnIDVk7ru3oQ,19708
-mkdocstrings_handlers/matlab/models.py,sha256=MqLZNL3um0yEeFSzv-xjzwjFpOyCdx7elyZ4X1ZV-yE,19228
+mkdocstrings_handlers/matlab/collect.py,sha256=6GkAwKor11Hm9QvKr6cKSHuylpoMF4Y3c8_myKiYOdE,29677
+mkdocstrings_handlers/matlab/enums.py,sha256=Lzc8MLar-uMoKplT5LxF1lXNBfjHc9MCTe2b0mJMc10,1540
+mkdocstrings_handlers/matlab/handler.py,sha256=5EK559dDElhNI9owKmia72Nl02MBULUaa1Dd-zCCeSE,19718
+mkdocstrings_handlers/matlab/models.py,sha256=2kMF7dyg5nPAzJt9G48IVtNAAq8K6xyKCBDDZHOBtUQ,19614
 mkdocstrings_handlers/matlab/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mkdocstrings_handlers/matlab/treesitter.py,sha256=FkWGuH7EmE_aO2qub5-_NnOVacYeXW353SkB7cNMlRo,21820
-mkdocstrings_handlers/matlab/templates/material/children.html.jinja,sha256=61OLBlQw3SaRscBkN7hVpbuSX2Bo7I0j_F581eDAUn8,6462
+mkdocstrings_handlers/matlab/treesitter.py,sha256=mpYNAoIU_nxvyisYLYzXllKjWKUKu0pkk8_e3RqVNaE,22284
+mkdocstrings_handlers/matlab/templates/material/children.html.jinja,sha256=xF_J8afiIciWTP1GBhGAGWXe36wl0zJBKCwa2uDQFbU,7409
 mkdocstrings_handlers/matlab/templates/material/folder.html.jinja,sha256=cWgaQH4EDFgL3eEIv0NRwRXYvtn9pp4tW7ntv3X2nM8,4076
 mkdocstrings_handlers/matlab/templates/material/namespace.html.jinja,sha256=a7Ya3YuN3hNEvqb_aG5Yr3QCuFYv6UhX5B26Gx2-tUQ,4099
 mkdocstrings_handlers/matlab/templates/material/property.html.jinja,sha256=anYCQM6AcyGgEApDC97TqzWlgVNtc1I_Ys1xyvUXye0,4396
-mkdocstrings_handlers/matlab/templates/material/style.css,sha256=0_Bs5_0fHM3X9l-IU1VHbZfhNA7nUw4SKEH_3zRhCDw,557
+mkdocstrings_handlers/matlab/templates/material/script.html.jinja,sha256=6bl-F1zDgBwgRaL76SFa_zyjKgyooofde6Vnq56DKso,4746
+mkdocstrings_handlers/matlab/templates/material/style.css,sha256=nCtnnMjJyDp6u2dZMRs4DIDTjmRdlS9oM2YdSMluVh0,690
 mkdocstrings_handlers/matlab/templates/material/summary.html.jinja,sha256=hVbQGxbMWd6fl01afbg0LhfYCJD1IRPmmCdcDBxU650,735
 mkdocstrings_handlers/matlab/templates/material/docstring/namespaces.html.jinja,sha256=jLtPxNNfZFO3-Ozy0eHqxHvKmlPCODML_5xt8SJr8UE,3165
 mkdocstrings_handlers/matlab/templates/material/docstring/properties.html.jinja,sha256=9ckdYymLlB5sflwYEaEPAQLJuVWF8nezMCV5JnanXVA,4165
 mkdocstrings_handlers/matlab/templates/material/summary/namespaces.html.jinja,sha256=0vVlUB6oh-A7cpXbuDLOQLxTubyb_DisdOKm062WNMs,650
 mkdocstrings_handlers/matlab/templates/material/summary/properties.html.jinja,sha256=nyPaELf9qPCxJQFxK1MWYK4fPwsk5VESh9xKHLtd-XE,643
-mkdocstrings_matlab-0.8.2.dist-info/METADATA,sha256=HXy7oTcI9VTg2cvY-OduEv9ugM4wyqeobHEgVLkkC_s,4736
-mkdocstrings_matlab-0.8.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mkdocstrings_matlab-0.8.2.dist-info/licenses/LICENSE,sha256=TZQpwBuA3KLH56--XDAY2Qwo9gGdxeTITYhMOylmYhg,743
-mkdocstrings_matlab-0.8.2.dist-info/RECORD,,
+mkdocstrings_matlab-0.9.1.dist-info/METADATA,sha256=nGcZZuakb88AhvWVFsfaDaZcr5pJJ7vYVGJUTa2a_Xw,4736
+mkdocstrings_matlab-0.9.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mkdocstrings_matlab-0.9.1.dist-info/licenses/LICENSE,sha256=TZQpwBuA3KLH56--XDAY2Qwo9gGdxeTITYhMOylmYhg,743
+mkdocstrings_matlab-0.9.1.dist-info/RECORD,,