mkdocstrings-matlab 0.9.4__tar.gz → 0.9.5__tar.gz

{mkdocstrings_matlab-0.9.4 → mkdocstrings_matlab-0.9.5}/CHANGELOG.md

@@ -1,6 +1,19 @@
 # CHANGELOG
 
 
+## v0.9.5 (2025-02-02)
+
+### Bug Fixes
+
+- Handle line continuations gracefully
+  ([#68](https://github.com/watermarkhu/mkdocstrings-matlab/pull/68),
+  [`8a32df0`](https://github.com/watermarkhu/mkdocstrings-matlab/commit/8a32df08f7ae8c4356db186e55d1ecdd3d537850))
+
+* handle line continuations gracefully
+
+* Update headings.md
+
+
 ## v0.9.4 (2025-02-01)
 
 ### Bug Fixes

{mkdocstrings_matlab-0.9.4 → mkdocstrings_matlab-0.9.5}/PKG-INFO

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

{mkdocstrings_matlab-0.9.4 → mkdocstrings_matlab-0.9.5}/docs/usage/configuration/headings.md

@@ -521,11 +521,13 @@ plugins:
 Show the symbol type in headings.
 
 This option will prefix headings with
-<code class="doc-symbol doc-symbol-attribute"></code>,
+<code class="doc-symbol doc-symbol-property"></code>,
 <code class="doc-symbol doc-symbol-function"></code>,
 <code class="doc-symbol doc-symbol-method"></code>,
-<code class="doc-symbol doc-symbol-class"></code> or
-<code class="doc-symbol doc-symbol-module"></code> types.
+<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_toc`][show_symbol_type_toc].
 
 ```yaml title="in mkdocs.yml (global configuration)"

{mkdocstrings_matlab-0.9.4 → mkdocstrings_matlab-0.9.5}/pyproject.toml

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

{mkdocstrings_matlab-0.9.4 → mkdocstrings_matlab-0.9.5}/scripts/copy_and_update_python_templates.py

@@ -1,9 +1,10 @@
 """A script to copy the modules and attributes templates from
 the python handler to the matlab handler and update the names"""
 
-from mkdocstrings_handlers.python.handler import PythonHandler
-from pathlib import Path
 import re
+from pathlib import Path
+
+from mkdocstrings_handlers.python.handler import PythonHandler
 
 # Get the templates directory of the python handler
 pythonHandler = PythonHandler("python", "material")

{mkdocstrings_matlab-0.9.4 → mkdocstrings_matlab-0.9.5}/src/mkdocstrings_handlers/matlab/__init__.py

@@ -1,9 +1,10 @@
 """MATLAB handler for mkdocstrings."""
 
-from mkdocstrings_handlers.matlab.handler import get_handler
-from mkdocstrings_handlers.matlab import collect, handler, models, treesitter
+from _griffe.docstrings import google, numpy
 from _griffe.enumerations import DocstringSectionKind
-from _griffe.docstrings import numpy, google
+
+from mkdocstrings_handlers.matlab import collect, handler, models, treesitter
+from mkdocstrings_handlers.matlab.handler import get_handler
 
 __all__ = ["get_handler", "collect", "handler", "models", "treesitter"]
 

{mkdocstrings_matlab-0.9.4 → mkdocstrings_matlab-0.9.5}/src/mkdocstrings_handlers/matlab/collect.py

@@ -3,35 +3,35 @@
 from collections import defaultdict, deque
 from copy import copy, deepcopy
 from pathlib import Path
-from typing import Any, Mapping, Sequence, Callable, TypeVar
+from typing import Any, Callable, Mapping, Sequence, TypeVar
 
-from _griffe.collections import LinesCollection as GLC, ModulesCollection
+from _griffe.collections import LinesCollection as GLC
+from _griffe.collections import ModulesCollection
 from _griffe.docstrings.models import (
+    DocstringParameter,
+    DocstringReturn,
     DocstringSectionOtherParameters,
     DocstringSectionParameters,
     DocstringSectionReturns,
-    DocstringParameter,
-    DocstringReturn,
 )
 from _griffe.enumerations import DocstringSectionKind
 from _griffe.expressions import Expr
 
 from mkdocstrings_handlers.matlab.enums import ParameterKind
 from mkdocstrings_handlers.matlab.models import (
-    _ParentGrabber,
     Class,
     Classfolder,
     Docstring,
     DocstringSectionText,
-    Function,
     Folder,
+    Function,
     MatlabMixin,
     Namespace,
     PathMixin,
+    _ParentGrabber,
 )
 from mkdocstrings_handlers.matlab.treesitter import FileParser
 
-
 PathType = TypeVar("PathType", bound=PathMixin)
 
 __all__ = ["LinesCollection", "PathCollection"]
@@ -198,7 +198,6 @@ 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():
- 
                 if absolute_path.suffix:
                     path, member = absolute_path.parent, absolute_path.stem
                 else:
@@ -549,9 +548,7 @@ class PathCollection(ModulesCollection):
             ]:
                 if member.parent.is_relative_to(self._config_path):
                     if member.parent not in self._folders:
-                        self._folders[member.parent] = LazyModel(
-                            member.parent, self
-                        )
+                        self._folders[member.parent] = LazyModel(member.parent, self)
                 else:
                     pass  # TODO: Issue warning?
 

{mkdocstrings_matlab-0.9.4 → mkdocstrings_matlab-0.9.5}/src/mkdocstrings_handlers/matlab/enums.py

@@ -1,5 +1,4 @@
 from enum import Enum
-from _griffe.enumerations import Kind as GriffeKind
 
 
 class Kind(str, Enum):
@@ -7,6 +6,7 @@ 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"

{mkdocstrings_matlab-0.9.4 → mkdocstrings_matlab-0.9.5}/src/mkdocstrings_handlers/matlab/handler.py

@@ -1,18 +1,18 @@
 """The mkdocstrings handler for processing MATLAB code documentation."""
 
-from pathlib import Path
+import re
 from collections import ChainMap
+from pathlib import Path
+from pprint import pprint
+from typing import Any, ClassVar, Mapping
+
 from jinja2.loaders import FileSystemLoader
 from markdown import Markdown
 from mkdocs.exceptions 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.base import BaseHandler, CollectionError, CollectorItem
 
 from mkdocstrings_handlers.matlab.collect import LinesCollection, PathCollection
+from mkdocstrings_handlers.python import rendering
 
 
 class MatlabHandler(BaseHandler):
@@ -363,7 +363,7 @@ class MatlabHandler(BaseHandler):
         except SyntaxError as ex:
             msg = str(ex)
             if ex.text:
-                msg += ':\n' + ex.text
+                msg += ":\n" + ex.text
             raise CollectionError(msg) from ex
         except Exception as ex:
             raise CollectionError(str(ex)) from ex

{mkdocstrings_matlab-0.9.4 → mkdocstrings_matlab-0.9.5}/src/mkdocstrings_handlers/matlab/models.py

@@ -153,12 +153,16 @@ class MatlabObject(Object):
 
     @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]
+        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
@@ -288,7 +292,8 @@ class Script(MatlabMixin, PathMixin, MatlabObject):
     This class inherits from `PathMixin` and `MatlabObject` to provide
     functionality specific to MATLAB scripts.
     """
-    kind = Kind.SCRIPT # type: ignore
+
+    kind = Kind.SCRIPT  # type: ignore
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
@@ -298,6 +303,7 @@ class Script(MatlabMixin, PathMixin, MatlabObject):
     def is_script(self) -> bool:
         return True
 
+
 class Class(MatlabMixin, PathMixin, GriffeClass, MatlabObject):
     """
     Represents a MATLAB class with additional properties and methods for handling
@@ -458,7 +464,7 @@ class Property(MatlabMixin, Attribute, MatlabObject):
         private = self.Access != AccessEnum.public
         get_private = self.GetAccess != AccessEnum.public
         return private or get_private
-    
+
     @property
     def is_private(self) -> bool:
         return self.Private or self.Hidden

{mkdocstrings_matlab-0.9.4 → mkdocstrings_matlab-0.9.5}/src/mkdocstrings_handlers/matlab/treesitter.py

@@ -1,15 +1,15 @@
 """Tree-sitter queries to extract information from MATLAB files."""
 
+import textwrap
 from collections import OrderedDict
-from typing import Any
-
-from tree_sitter import Language, Parser, Node
-import tree_sitter_matlab as tsmatlab
-
 from pathlib import Path
+from typing import Any
 
 import charset_normalizer
+import tree_sitter_matlab as tsmatlab
+from tree_sitter import Language, Node, Parser
 
+from mkdocstrings_handlers.matlab.enums import ParameterKind
 from mkdocstrings_handlers.matlab.models import (
     AccessEnum,
     Class,
@@ -17,13 +17,11 @@ from mkdocstrings_handlers.matlab.models import (
     Docstring,
     Function,
     MatlabMixin,
-    Parameters,
     Parameter,
+    Parameters,
     Property,
     Script,
 )
-from mkdocstrings_handlers.matlab.enums import ParameterKind
-
 
 __all__ = ["FileParser"]
 
@@ -32,44 +30,52 @@ LANGUAGE = Language(tsmatlab.language())
 
 PARSER = Parser(LANGUAGE)
 
-FILE_QUERY = LANGUAGE.query("""(source_file
+FILE_QUERY = LANGUAGE.query("""(source_file .
     (comment)* @header .
-    (function_definition)? @function .
-    (class_definition)? @class
+    [
+        (function_definition) @function
+        (class_definition) @class
+    ]?
 )
 """)
 
 
 FUNCTION_QUERY = LANGUAGE.query("""(function_definition .
-    ("function") .
+    ("function")
     (function_output . 
         [
             (identifier) @output
             (multioutput_variable .
-                ((identifier) @output (",")?)*
+                [
+                    (identifier) @output
+                    _
+                ]*
             )
         ]
-    )? .
+    )?
     [
         ("set.") @setter
         ("get.") @getter
-    ]? .
-    (identifier) @name .
+    ]?
+    (identifier) @name
     (function_arguments .
-        ((identifier) @input (",")?)*
-    )? .
-    (comment)* @docstring .
+        [
+            (identifier) @input 
+            _
+        ]*
+    )?
+    (comment)* @docstring
     (arguments_statement)* @arguments
 )""")
 
 
 ARGUMENTS_QUERY = LANGUAGE.query("""(arguments_statement .
-    ("arguments") .
+    ("arguments")
     (attributes
         (identifier) @attributes
-    )? .
-    (comment)? .
-    ("\\n")? .
+    )?
+    (comment)?
+    ("\\n")?
     (property)+ @arguments
 )""")
 
@@ -82,22 +88,22 @@ PROPERTY_QUERY = LANGUAGE.query("""(property .
             (".") .
             (identifier) @name
         )
-    ] .
-    (dimensions)? @dimensions .
-    (identifier)? @class .
-    (validation_functions)? @validators .
+    ]
+    (dimensions)? @dimensions
+    (identifier)? @class
+    (validation_functions)? @validators
     (default_value
-        ("=") .
+        ("=")
         _+ @default
-    )? .
+    )?
     (comment)* @comment              
 )""")
 
 
 ATTRIBUTE_QUERY = LANGUAGE.query("""(attribute
-    (identifier) @name .
+    (identifier) @name
     (
-        ("=") .
+        ("=")
         _+ @value
     )?
 )""")
@@ -106,13 +112,13 @@ ATTRIBUTE_QUERY = LANGUAGE.query("""(attribute
 CLASS_QUERY = LANGUAGE.query("""("classdef" .
     (attributes
         (attribute) @attributes
-    )? .
-    (identifier) @name .
+    )?
+    (identifier) @name
     (superclasses
         (property_name) @bases             
     )? .
-    (comment)* @docstring .
-    ("\\n")? .
+    (comment)* @docstring
+    ("\\n")?
     [
         (comment)
         (methods) @methods
@@ -165,12 +171,9 @@ def _dedent(lines: list[str]) -> list[str]:
     Returns:
         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) if indents else 0
-    if indent == 0:
-        return lines
-    else:
-        return [line[indent:] if line.strip() else line for line in lines]
+    text = "\n".join(lines)
+    dedented_text = textwrap.dedent(text)
+    return dedented_text.split("\n")
 
 
 class FileParser(object):
@@ -248,12 +251,14 @@ class FileParser(object):
 
             return model
         except Exception as ex:
-            syntax_error = SyntaxError(f"Error parsing Matlab file")
+            syntax_error = SyntaxError("Error parsing Matlab file")
             syntax_error.filename = str(self.filepath)
             if self._node is not None:
                 if self._node.text is not None:
-                    indentation = ' ' * self._node.start_point.column
-                    syntax_error.text = indentation + self._node.text.decode(self.encoding)
+                    indentation = " " * self._node.start_point.column
+                    syntax_error.text = indentation + self._node.text.decode(
+                        self.encoding
+                    )
                 syntax_error.lineno = self._node.start_point.row + 1
                 syntax_error.offset = self._node.start_point.column + 1
                 syntax_error.end_lineno = self._node.end_point.row + 1
@@ -428,7 +433,9 @@ class FileParser(object):
 
         return (key, value)
 
-    def _parse_function(self, node: Node, method: bool = False, **kwargs: Any) -> Function:
+    def _parse_function(
+        self, node: Node, method: bool = False, **kwargs: Any
+    ) -> Function:
         """
         Parse a function node and return a Function model.
 
@@ -610,11 +617,19 @@ 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
+            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
@@ -640,13 +655,13 @@ class FileParser(object):
 
             # Exclude all pragma's
             if line in [
-                '%#codegen',
-                '%#eml',
-                '%#external',
-                '%#exclude',
-                '%#function',
-                '%#ok',
-                '%#mex',
+                "%#codegen",
+                "%#eml",
+                "%#external",
+                "%#exclude",
+                "%#function",
+                "%#ok",
+                "%#mex",
             ]:
                 continue
 

mkdocstrings_matlab-0.9.5/test/playground.py

@@ -0,0 +1,7 @@
+from pathlib import Path
+
+from mkdocstrings_handlers.matlab.treesitter import FileParser
+
+file = Path(__file__).parent.parent / "docs" / "snippets" / "+mynamespace" / "typed_function.m"
+parser = FileParser(file.resolve())
+parser.parse()

{mkdocstrings_matlab-0.9.4 → mkdocstrings_matlab-0.9.5}/docs/debug.py

@@ -1,8 +1,8 @@
+import os
 from contextlib import contextmanager
-from mkdocs.commands import serve
 from pathlib import Path
 
-import os
+from mkdocs.commands import serve
 
 
 @contextmanager