feat: add supports for scripts (#51)

* fix: script does not have kind
* fix: tree-sitter query fixes 
* fix: do not check for property SetAccess for private
* feat: add support for scripts
* doc: update namespace contents
* fix: select only the first comment block as docstring

Author: watermarkhu

docs/snippets/+mynamespace/mynamespace.md

@@ -8,6 +8,7 @@
             classA.m
             classB.m
             typed_function.m
+            myscript.m
         ```
 
     === ":material-file-code: `readme.md`"
@@ -32,4 +33,10 @@
 
         ```matlab
         --8<-- "docs/snippets/+mynamespace/typed_function.m"
-        ```
+        ```
+
+    === ":material-file-code: `myscript.m`"
+
+        ```matlab
+        --8<-- "docs/snippets/+mynamespace/myscript.m"
+        ```

docs/snippets/+mynamespace/myscript.m

@@ -0,0 +1,4 @@
+% This is an example script.
+
+% This is a paragraph. 
+disp('hello world');

docs/usage/configuration/headings.md

@@ -595,6 +595,7 @@ This option will prefix items in the ToC with
 <code class="doc-symbol doc-symbol-function"></code>,
 <code class="doc-symbol doc-symbol-method"></code>,
 <code class="doc-symbol doc-symbol-class"></code>,
+<code class="doc-symbol doc-symbol-script"></code>,
 <code class="doc-symbol doc-symbol-namespace"></code> or.
 <code class="doc-symbol doc-symbol-folder"></code> types.
 See also [`show_symbol_type_heading`][show_symbol_type_heading].
@@ -621,6 +622,7 @@ plugins:
         <ul style="list-style: none;">
           <li><code class="doc-symbol doc-symbol-folder"></code> folder</li>
           <li><code class="doc-symbol doc-symbol-namespace"></code> namespace</li>
+          <li><code class="doc-symbol doc-symbol-script"></code> script</li>
           <li><code class="doc-symbol doc-symbol-function"></code> function</li>
           <li><code class="doc-symbol doc-symbol-class"></code> Class
             <ul style="list-style: none;">
@@ -635,6 +637,7 @@ plugins:
         <ul style="list-style: none;">
           <li>folder</li>
           <li>namespace</li>
+          <li>script</li>
           <li>function</li>
           <li>Class
             <ul style="list-style: none;">

docs/usage/configuration/members.md

@@ -169,16 +169,15 @@ To simplify the definition here, any property or method that do not have attribu
 ```mermaid 
 flowchart TD
 a[Access=public]
-sg[SetAccess=public/immutable and GetAccess=public]
+ga[GetAccess=public]
 
 public[not private member]
 private[private member]
 a -- yes --> public 
 a -- no --> private
-a -- "not specified" --> sg
-sg -- no --> private
-sg -- yes --> public
-
+a -- "not specified" --> ga
+ga -- no --> private
+ga -- yes --> public
 ```
 
 This takes precedence over [`members`][] and [`filters`][], and also applies for [`inherited_members`][]. This means that for any private member to be shown, `private_members` must be enabled, and further selection is possible via [`members`][] and [`filters`][]. Private members will be labeled with it access attribute setting, this can be disabled in [`show_labels`][]. 

scripts/copy_and_update_python_templates.py

@@ -112,7 +112,7 @@ def copy_template(
 )
 
 ## Copy children template
-copy_template(
+(targetFile, content) = copy_template(
     "_base/children.html.jinja",
     "children.html.jinja",
     {
@@ -124,3 +124,32 @@ def copy_template(
         "{% elif child.is_module and config.show_submodules %}": "{% elif (child.is_namespace and config.show_subnamespaces) or obj.is_folder %}",
     },
 )
+
+
+scripts = """{% 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 %}
+
+        
+"""
+
+index = content.find("{% if config.show_subnamespaces or obj.is_folder %}")
+content = content[:index] + scripts[:-1] + content[index:]
+targetFile.write_text(content)

src/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 @@ def _collect_parent(self, path: Path) -> _ParentGrabber | None:
             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
 

src/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):

src/mkdocstrings_handlers/matlab/models.py

@@ -17,7 +17,7 @@
     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 @@ def __init__(
     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 @@ def __init__(
     @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

src/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,

src/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>

src/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: #fff8a87b;
+}
+
+code.doc-symbol-script::after {
+  content: "prog";
+}