mkdocstrings-matlab 0.6.0__py3-none-any.whl → 0.7.0__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
+from typing import Mapping, Sequence, Callable, TypeVar
 
 from _griffe.collections import LinesCollection as GLC, ModulesCollection
 from _griffe.docstrings.models import (
@@ -24,14 +24,16 @@ from mkdocstrings_handlers.matlab.models import (
     Docstring,
     DocstringSectionText,
     Function,
+    Folder,
     MatlabMixin,
-    Object,
     Namespace,
-    ROOT,
+    PathMixin,
 )
 from mkdocstrings_handlers.matlab.treesitter import FileParser
 
 
+PathType = TypeVar("PathType", bound=PathMixin)
+
 __all__ = ["LinesCollection", "PathCollection"]
 
 
@@ -104,6 +106,7 @@ class PathCollection(ModulesCollection):
         matlab_path (Sequence[str | Path]): A list of strings or Path objects representing the MATLAB paths.
         recursive (bool, optional): If True, recursively adds all subdirectories of the given paths to the search path. Defaults to False.
         config (Mapping, optional): Configuration settings for the PathCollection. Defaults to {}.
+        config_path (Path | None, optional): The path to the configuration file. Defaults to None.
 
     Methods:
         members() -> dict:
@@ -130,6 +133,7 @@ class PathCollection(ModulesCollection):
         matlab_path: Sequence[str | Path],
         recursive: bool = False,
         config: Mapping = {},
+        config_path: Path | None = None,
     ) -> None:
         """
         Initialize an instance of PathCollection.
@@ -148,6 +152,8 @@ 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._config_path = config_path
 
         self.config = config
         self.lines_collection = LinesCollection()
@@ -188,6 +194,26 @@ class PathCollection(ModulesCollection):
             model = self._models[self._mapping[identifier][0]].model()
             if model is not None:
                 model = self.update_model(model, config)
+
+        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
+                else:
+                    member = None
+                lazymodel = self._folders.get(str(path), None)
+
+                if lazymodel is not None:
+                    model = lazymodel.model()
+                    if model is not None and member is not None:
+                        model = model.members.get(member, None)
+                else:
+                    model = None
+            else:
+                model = None
+
         else:
             model = None
             name_parts = identifier.split(".")
@@ -511,13 +537,25 @@ class PathCollection(ModulesCollection):
         else:
             self._path.appendleft(path)
 
-        members = PathGlobber(path, recursive=recursive)
-        for member in members:
+        for member in PathGlobber(path, recursive=recursive):
             model = LazyModel(member, self)
             self._models[member] = model
             self._mapping[model.name].append(member)
             self._members[path].append((model.name, member))
 
+            if self._config_path is not None and member.parent.stem[0] not in [
+                "+",
+                "@",
+            ]:
+                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(
+                            member.parent, self
+                        )
+                else:
+                    pass  # TODO: Issue warning?
+
     def rm_path(self, path: str | Path, recursive: bool = False):
         """
         Removes a path from the search path and updates the namespace and database accordingly.
@@ -610,6 +648,10 @@ class LazyModel:
         self._path_collection: PathCollection = path_collection
         self._lines_collection: LinesCollection = path_collection.lines_collection
 
+    @property
+    def is_folder(self) -> bool:
+        return self._path.is_dir() and self._path.name[0] not in ["+", "@"]
+
     @property
     def is_class_folder(self) -> bool:
         return self._path.is_dir() and self._path.name[0] == "@"
@@ -648,7 +690,7 @@ class LazyModel:
         else:
             return name
 
-    def model(self):
+    def model(self) -> MatlabMixin | None:
         if not self._path.exists():
             return None
 
@@ -657,19 +699,22 @@ class LazyModel:
                 self._model = self._collect_classfolder(self._path)
             elif self.is_namespace:
                 self._model = self._collect_namespace(self._path)
+            elif self.is_folder:
+                self._model = self._collect_folder(self._path)
             else:
                 self._model = self._collect_path(self._path)
         if self._model is not None:
             self._model.parent = self._collect_parent(self._path.parent)
         return self._model
 
-    def _collect_parent(self, path: Path) -> Object | _ParentGrabber:
+    def _collect_parent(self, path: Path) -> _ParentGrabber | None:
         if self.is_in_namespace:
-            parent = _ParentGrabber(
-                lambda: self._path_collection._models[path].model() or ROOT
-            )
+            grabber: Callable[[], MatlabMixin | None] = self._path_collection._models[
+                path
+            ].model
+            parent = _ParentGrabber(grabber)
         else:
-            parent = ROOT
+            parent = None
         return parent
 
     def _collect_path(self, path: Path) -> MatlabMixin:
@@ -678,6 +723,27 @@ class LazyModel:
         self._lines_collection[path] = file.content.split("\n")
         return model
 
+    def _collect_directory(self, path: Path, model: PathType) -> PathType:
+        for member in path.iterdir():
+            if member.is_dir() and member.name[0] in ["+", "@"]:
+                submodel = self._path_collection._models[member].model()
+                if submodel is not None:
+                    model.members[submodel.name] = submodel
+
+            elif member.is_file() and member.suffix == ".m":
+                if member.name == "Contents.m":
+                    contentsfile = self._collect_path(member)
+                    model.docstring = contentsfile.docstring
+                else:
+                    submodel = self._path_collection._models[member].model()
+                    if submodel is not None:
+                        model.members[submodel.name] = submodel
+
+        if model.docstring is None:
+            model.docstring = self._collect_readme_md(path, model)
+
+        return model
+
     def _collect_classfolder(self, path: Path) -> Classfolder | None:
         classfile = path / (path.name[1:] + ".m")
         if not classfile.exists():
@@ -698,31 +764,17 @@ class LazyModel:
             model.docstring = self._collect_readme_md(path, model)
         return model
 
-    def _collect_namespace(self, path: Path) -> Namespace | None:
+    def _collect_namespace(self, path: Path) -> Namespace:
         name = self.name[1:].split(".")[-1]
         model = Namespace(name, filepath=path, path_collection=self._path_collection)
+        return self._collect_directory(path, model)
 
-        for member in path.iterdir():
-            if member.is_dir() and member.name[0] in ["+", "@"]:
-                submodel = self._path_collection._models[member].model()
-                if submodel is not None:
-                    model.members[submodel.name] = submodel
-
-            elif member.is_file() and member.suffix == ".m":
-                if member.name == "Contents.m":
-                    contentsfile = self._collect_path(member)
-                    model.docstring = contentsfile.docstring
-                else:
-                    submodel = self._path_collection._models[member].model()
-                    if submodel is not None:
-                        model.members[submodel.name] = submodel
-
-        if model.docstring is None:
-            model.docstring = self._collect_readme_md(path, model)
-
-        return model
+    def _collect_folder(self, path: Path) -> Folder:
+        name = path.stem
+        model = Folder(name, filepath=path, path_collection=self._path_collection)
+        return self._collect_directory(path, model)
 
-    def _collect_readme_md(self, path, parent: MatlabMixin) -> Docstring | None:
+    def _collect_readme_md(self, path, parent: PathMixin) -> Docstring | None:
         if (path / "README.md").exists():
             readme = path / "README.md"
         elif (path / "readme.md").exists():

mkdocstrings_handlers/matlab/handler.py

@@ -176,13 +176,14 @@ class MatlabHandler(BaseHandler):
         super().__init__(*args, **kwargs)
 
         if paths is None or config_file_path is None:
+            config_path = None
             full_paths = []
         else:
             config_path = Path(config_file_path).parent
             full_paths = [(config_path / path).resolve() for path in paths]
 
         self.paths: PathCollection = PathCollection(
-            full_paths, recursive=paths_recursive
+            full_paths, recursive=paths_recursive, config_path=config_path
         )
         self.lines: LinesCollection = self.paths.lines_collection
         self._locale: str = locale
@@ -253,9 +254,7 @@ class MatlabHandler(BaseHandler):
             }
 
         # Map docstring options
-        final_config["show_submodules"] = config.get(
-            "show_subnamespaces", False
-        )
+        final_config["show_submodules"] = config.get("show_subnamespaces", False)
         final_config["show_docstring_attributes"] = config.get(
             "show_docstring_properties", True
         )

mkdocstrings_handlers/matlab/models.py

@@ -99,7 +99,7 @@ class _ParentGrabber:
         __call__(): Calls the grabber function and returns a MatlabObject.
     """
 
-    def __init__(self, grabber: "Callable[[], Object]") -> None:
+    def __init__(self, grabber: "Callable[[], MatlabMixin | None]") -> None:
         """
         Initializes the _ParentGrabber with a grabber function.
 
@@ -109,7 +109,7 @@ class _ParentGrabber:
         self._grabber = grabber
 
     @property
-    def parent(self) -> "Object":
+    def parent(self) -> "MatlabMixin | None":
         """
         Calls the grabber function and returns a MatlabObject.
 
@@ -156,7 +156,7 @@ class MatlabObject(Object):
         Returns:
             str: The canonical path of the object.
         """
-        if isinstance(self.parent, _Root):
+        if self.parent is None:
             return self.name
 
         if isinstance(self.parent, MatlabObject):
@@ -165,7 +165,7 @@ class MatlabObject(Object):
             parent = getattr(self.parent, "model", self.parent)
 
         if isinstance(parent, Classfolder) and self.name == parent.name:
-            if isinstance(parent.parent, _Root) or parent.parent is None:
+            if parent.parent is None:
                 return self.name
             else:
                 return f"{parent.parent.canonical_path}.{self.name}"
@@ -173,23 +173,6 @@ class MatlabObject(Object):
             return f"{parent.canonical_path}.{self.name}" if parent else self.name
 
 
-class _Root(MatlabObject):
-    """
-    A class representing the root object in a MATLAB structure.
-    All the objects that have the root object as parent are at the top level,
-    and can be called directly.
-    """
-
-    def __init__(self) -> None:
-        super().__init__("ROOT", parent=None)
-
-    def __repr__(self) -> str:
-        return "MATLABROOT"
-
-
-ROOT = _Root()
-
-
 class PathMixin(Object):
     """
     A mixin class that provides a filepath attribute and related functionality.
@@ -200,7 +183,6 @@ class PathMixin(Object):
 
     def __init__(self, *args: Any, filepath: Path | None = None, **kwargs: Any) -> None:
         self._filepath: Path | None = filepath
-
         super().__init__(*args, **kwargs)
 
     @property
@@ -215,22 +197,22 @@ class MatlabMixin(Object):
     def __init__(
         self,
         *args: Any,
-        parent: "Class | Classfolder | Namespace | _Root | None" = None,
+        parent: "Class | Classfolder | Namespace | None" = None,
         docstring: Docstring | None = None,
         **kwargs: Any,
     ):
-        self._parent: "Class | Classfolder | Namespace | _Root | _ParentGrabber | None" = parent
+        self._parent: "Class | Classfolder | Namespace | _ParentGrabber | None" = parent
         self._docstring: Docstring | None = docstring
         super().__init__(*args, **kwargs)
 
     @property
-    def parent(self) -> Object:
+    def parent(self) -> Object | None:
         if isinstance(self._parent, MatlabMixin):
             return self._parent
         elif isinstance(self._parent, _ParentGrabber):
             return self._parent.parent
         else:
-            return ROOT
+            return None
 
     @parent.setter
     def parent(self, value):
@@ -559,14 +541,34 @@ class Function(MatlabMixin, PathMixin, GriffeFunction, MatlabObject):
         pass
 
 
+class Folder(MatlabMixin, PathMixin, Module, MatlabObject):
+    """
+    A class representing a Folder in a MATLAB project.
+
+    Inherits from:
+        - MatlabMixin: A mixin class providing MATLAB-specific functionality.
+        - PathMixin: A mixin class providing path-related functionality.
+        - Module: A class representing a module.
+        - MatlabObject: A base class for MATLAB objects.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.labels = {"Folder"}
+
+    def __repr__(self) -> str:
+        return f"Folder({self.path!r})"
+
+
 class Namespace(MatlabMixin, PathMixin, Module, MatlabObject):
     """
     A class representing a namespace in a MATLAB project.
 
     Inherits from:
+        - MatlabMixin: A mixin class providing MATLAB-specific functionality.
         - PathMixin: A mixin class providing path-related functionality.
-        - MatlabObject: A base class for MATLAB objects.
         - Module: A class representing a module.
+        - MatlabObject: A base class for MATLAB objects.
     """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:

{mkdocstrings_matlab-0.6.0.dist-info → mkdocstrings_matlab-0.7.0.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-matlab
-Version: 0.6.0
+Version: 0.7.0
 Summary: A MATLAB handler for mkdocstrings
 Author-email: Mark Hu <watermarkhu@gmail.com>
-License: ISC
+License: MIT
 License-File: LICENSE
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -40,7 +40,7 @@ Description-Content-Type: text/markdown
 [![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://watermarkhu.nl/mkdocstrings-matlab)
 [![pypi version](https://img.shields.io/pypi/v/mkdocstrings-matlab.svg)](https://pypi.org/project/mkdocstrings-matlab/)
 
-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/). 
+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. The AST information are imported as custom [Griffe](https://mkdocstrings.github.io/griffe/) objects and mocked for the [python handler](https://mkdocstrings.github.io/python/). 
 
 
 You can install this handler by specifying it as a dependency:
@@ -64,10 +64,10 @@ dependencies = [
 
 - **Support for argument validation blocks:** Tree-sitter collects your [function and method argument validation](https://mathworks.com/help/matlab/matlab_prog/function-argument-validation-1.html)
    blocks to display input and output argument types and default values. 
-   It is even able to automatically add cross-references o other objects from your API.
+   It is even able to automatically add cross-references to other objects from your API.
 
-- **Recursive documentation of MATLAB [namespaces](https://mathworks.com/help/matlab/matlab_oop/namespaces.html):** 
-  just add `+` to the identifer, and you get the full namespace docs. You don't need to inject documentation for each class, function, and script. Additionaly, the parent namespace documentation will be either extracted from the `Contents.m` or the `readme.md` file at the root of the namespace. 
+- **Recursive documentation of MATLAB [namespaces](https://mathworks.com/help/matlab/matlab_oop/namespaces.html) and folders:** 
+  just add `+` to the identifer for namespaces or the relative path for folder, and you get documentation for the entire directory. You don't need to inject documentation for each class, function, and script. Additionaly, the directory documentation will be either extracted from the `Contents.m` or the `readme.md` file at the root of the namespace or folder.
 
 - **Support for documented properties:** properties definitions followed by a docstring will be recognized in classes. 
 

{mkdocstrings_matlab-0.6.0.dist-info → mkdocstrings_matlab-0.7.0.dist-info}/RECORD

@@ -2,14 +2,14 @@ mkdocs_material_matlab/__init__.py,sha256=9pmrwWbkIyr0T7qvADbsz3OR5bB3rWb231e6JS
 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=w5R9cGtqeJF0GUP_Jc_ad8FnS4FpbutnmHvzVRlohPM,1124
-mkdocstrings_handlers/matlab/collect.py,sha256=i9OudR4oJX-ELPL4GVv_AJSA5N6iZk-zTSY58dfWGNw,27512
+mkdocstrings_handlers/matlab/collect.py,sha256=WXuRIDYL0T1fKv1MwwOC6uWAB80PxRCs4uYDgOHiQcg,29749
 mkdocstrings_handlers/matlab/enums.py,sha256=lr3wLlhPxyBym3O7Rt0cLUZYqPCz6wQ2PYBibLKLTek,982
-mkdocstrings_handlers/matlab/handler.py,sha256=koMpRSftxQbI8R2l0fGfBOe36yUkne6lATwDauBa5w0,18676
-mkdocstrings_handlers/matlab/models.py,sha256=7WWZ-nLaL0dWF-vOYWP-O3kNEGKtMfa5DK_J23mkhhU,18174
+mkdocstrings_handlers/matlab/handler.py,sha256=-KA6kj8L55T9jxgKzNM_k59AXsyTSQJqFd8ltN00LQI,18710
+mkdocstrings_handlers/matlab/models.py,sha256=0qGk6UrGHB4fC49I2cjCgqLFAIozqtmLAxl9PPN6Blc,18461
 mkdocstrings_handlers/matlab/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mkdocstrings_handlers/matlab/treesitter.py,sha256=FkWGuH7EmE_aO2qub5-_NnOVacYeXW353SkB7cNMlRo,21820
-mkdocstrings_matlab-0.6.0.dist-info/METADATA,sha256=3Q5DCapIgie22A0okETTVhAkZKtde7wJ_G5W4SgRkJM,4779
-mkdocstrings_matlab-0.6.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mkdocstrings_matlab-0.6.0.dist-info/entry_points.txt,sha256=qUZFuB2TKh7KPlg4dR2npfbNgNExw6O6j1vF276PtPw,92
-mkdocstrings_matlab-0.6.0.dist-info/licenses/LICENSE,sha256=TZQpwBuA3KLH56--XDAY2Qwo9gGdxeTITYhMOylmYhg,743
-mkdocstrings_matlab-0.6.0.dist-info/RECORD,,
+mkdocstrings_matlab-0.7.0.dist-info/METADATA,sha256=5jzSXQm4dSLd9GBaJWSAvJm1JGBcuAGUaLWLpMoiGu0,4736
+mkdocstrings_matlab-0.7.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mkdocstrings_matlab-0.7.0.dist-info/entry_points.txt,sha256=qUZFuB2TKh7KPlg4dR2npfbNgNExw6O6j1vF276PtPw,92
+mkdocstrings_matlab-0.7.0.dist-info/licenses/LICENSE,sha256=TZQpwBuA3KLH56--XDAY2Qwo9gGdxeTITYhMOylmYhg,743
+mkdocstrings_matlab-0.7.0.dist-info/RECORD,,