mkdocstrings-matlab 0.8.1__tar.gz → 0.9.0__tar.gz

{mkdocstrings_matlab-0.8.1 → mkdocstrings_matlab-0.9.0}/.github/workflows/release.yaml

@@ -93,7 +93,7 @@ jobs:
     concurrency:
       group: gh-pages
       cancel-in-progress: false
-      
+
     steps:
       - name: checkout repository
         uses: actions/checkout@v4
@@ -113,6 +113,7 @@ jobs:
         run: |
           git config --global user.name github-actions[bot]
           git config --global user.email 41898282+github-actions[bot]@users.noreply.github.com
+          git fetch origin gh-pages:gh-pages
   
       - name: delete testing documentation
         continue-on-error: true

{mkdocstrings_matlab-0.8.1 → mkdocstrings_matlab-0.9.0}/CHANGELOG.md

@@ -1,6 +1,26 @@
 # CHANGELOG
 
 
+## v0.9.0 (2025-01-16)
+
+### Features
+
+- Add supports for scripts ([#51](https://github.com/watermarkhu/mkdocstrings-matlab/pull/51),
+  [`ecefc80`](https://github.com/watermarkhu/mkdocstrings-matlab/commit/ecefc801e730cf3ab1d5889ecbfc400af0591385))
+
+* 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
+
+
+## v0.8.2 (2025-01-14)
+
+### Bug Fixes
+
+- Allow mkdocs.yml in subdir ([#50](https://github.com/watermarkhu/mkdocstrings-matlab/pull/50),
+  [`8889349`](https://github.com/watermarkhu/mkdocstrings-matlab/commit/88893497c7e12fdc0bb6c00798d7ed3357a881f9))
+
+
 ## v0.8.1 (2025-01-14)
 
 ### Bug Fixes

{mkdocstrings_matlab-0.8.1 → mkdocstrings_matlab-0.9.0}/PKG-INFO

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

{mkdocstrings_matlab-0.8.1 → mkdocstrings_matlab-0.9.0}/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"
+        ```

mkdocstrings_matlab-0.9.0/docs/snippets/+mynamespace/myscript.m

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

{mkdocstrings_matlab-0.8.1 → mkdocstrings_matlab-0.9.0}/docs/usage/configuration/headings.md

@@ -530,7 +530,6 @@ See also [`show_symbol_type_toc`][show_symbol_type_toc].
 
 ```yaml title="in mkdocs.yml (global configuration)"
 plugins:
-- mkdocs-material-matlab # (1)
 - mkdocstrings:
     handlers:
       matlab:
@@ -538,8 +537,6 @@ plugins:
           show_symbol_type_heading: true
 ```
 
-1. :warning: When using material theme, make sure to also enable the plugin `mkdocs-material-matlab` such that the right heading types are displayed. Otherwise, <code class="doc-symbol doc-symbol-attribute"></code> will be shown as `attr` and <code class="doc-symbol doc-symbol-module"></code> will be shown as `mod`, as the mkdocstrings-matlab plugin is reusing assets from mkdocstrings-python. 
-
 ```md title="or in docs/some_page.md (local configuration)"
 ::: matlab_callable
     options:
@@ -598,13 +595,13 @@ 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].
 
 ```yaml title="in mkdocs.yml (global configuration)"
 plugins:
-- mkdocs-material-matlab # (1)
 - mkdocstrings:
     handlers:
       matlab:
@@ -612,9 +609,6 @@ plugins:
           show_symbol_type_toc: true
 ```
 
-1. :warning: When using material theme, make sure to also enable the plugin `mkdocs-material-matlab` such that the right heading types are displayed. 
-
-
 ```md title="or in docs/some_page.md (local configuration)"
 ::: matlab_callable
     options:
@@ -628,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;">
@@ -642,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;">

{mkdocstrings_matlab-0.8.1 → mkdocstrings_matlab-0.9.0}/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`][]. 

{mkdocstrings_matlab-0.8.1 → mkdocstrings_matlab-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocstrings-matlab"
-version = "0.8.1"
+version = "0.9.0"
 description = "A MATLAB handler for mkdocstrings"
 authors = [
     { name = "Mark Hu", email = "watermarkhu@gmail.com" }

{mkdocstrings_matlab-0.8.1 → mkdocstrings_matlab-0.9.0}/scripts/copy_and_update_python_templates.py

@@ -112,7 +112,7 @@ copy_template(
 )
 
 ## Copy children template
-copy_template(
+(targetFile, content) = copy_template(
     "_base/children.html.jinja",
     "children.html.jinja",
     {
@@ -124,3 +124,32 @@ 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)

{mkdocstrings_matlab-0.8.1 → mkdocstrings_matlab-0.9.0}/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 (
@@ -152,7 +152,7 @@ class PathCollection(ModulesCollection):
         self._mapping: dict[str, deque[Path]] = defaultdict(deque)
         self._models: dict[Path, LazyModel] = {}
         self._members: dict[Path, list[tuple[str, Path]]] = defaultdict(list)
-        self._folders: dict[str, LazyModel] = {}
+        self._folders: dict[Path, LazyModel] = {}
         self._config_path = config_path
 
         self.config = config
@@ -198,12 +198,12 @@ class PathCollection(ModulesCollection):
         elif self._config_path is not None and "/" in identifier:
             absolute_path = (self._config_path / Path(identifier)).resolve()
             if absolute_path.exists():
-                path = absolute_path.relative_to(self._config_path)
-                if path.suffix:
-                    path, member = path.parent, path.stem
+ 
+                if absolute_path.suffix:
+                    path, member = absolute_path.parent, absolute_path.stem
                 else:
-                    member = None
-                lazymodel = self._folders.get(str(path), None)
+                    path, member = absolute_path, None
+                lazymodel = self._folders.get(path, None)
 
                 if lazymodel is not None:
                     model = lazymodel.model()
@@ -548,9 +548,8 @@ class PathCollection(ModulesCollection):
                 "@",
             ]:
                 if member.parent.is_relative_to(self._config_path):
-                    relative_path = member.parent.relative_to(self._config_path)
                     if member.parent not in self._folders:
-                        self._folders[str(relative_path)] = LazyModel(
+                        self._folders[member.parent] = LazyModel(
                             member.parent, self
                         )
                 else:
@@ -717,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_matlab-0.8.1 → mkdocstrings_matlab-0.9.0}/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):

{mkdocstrings_matlab-0.8.1 → mkdocstrings_matlab-0.9.0}/src/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_matlab-0.8.1 → mkdocstrings_matlab-0.9.0}/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,

mkdocstrings_matlab-0.9.0/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>

{mkdocstrings_matlab-0.8.1 → mkdocstrings_matlab-0.9.0}/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";
+}

{mkdocstrings_matlab-0.8.1 → mkdocstrings_matlab-0.9.0}/src/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(