mkdocstrings-matlab 0.6.0__py3-none-any.whl → 0.8.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

@@ -2,8 +2,9 @@
 
 from pathlib import Path
 from collections import ChainMap
+from jinja2.loaders import FileSystemLoader
 from markdown import Markdown
-from mkdocstrings.extension import PluginError
+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
@@ -152,7 +153,9 @@ class MatlabHandler(BaseHandler):
 
     def __init__(
         self,
-        *args: Any,
+        handler: str,
+        theme: str,
+        custom_templates: str | None = None,
         config_file_path: str | None = None,
         paths: list[str] | None = None,
         paths_recursive: bool = False,
@@ -163,7 +166,9 @@ class MatlabHandler(BaseHandler):
         Initialize the handler with the given configuration.
 
         Args:
-            *args (Any): Variable length argument list.
+            handler: The name of the handler.
+            theme: The name of theme to use.
+            custom_templates: Directory containing custom templates.
             config_file_path (str | None, optional): Path to the configuration file. Defaults to None.
             paths (list[str] | None, optional): List of paths to include. Defaults to None.
             paths_recursive (bool, optional): Whether to include paths recursively. Defaults to False.
@@ -173,21 +178,37 @@ class MatlabHandler(BaseHandler):
         Returns:
             None
         """
-        super().__init__(*args, **kwargs)
+
+        super().__init__(handler, theme, custom_templates=custom_templates)
+
+        theme_path = Path(__file__).resolve().parent / "templates" / theme
+        if theme_path.exists() and isinstance(self.env.loader, FileSystemLoader):
+            # Insert our templates directory at the beginning of the search path to overload the Python templates
+            self.env.loader.searchpath.insert(0, str(theme_path))
+        css_path = theme_path / "style.css"
+        if css_path.exists():
+            self.extra_css += "\n" + css_path.read_text(encoding="utf-8")
 
         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]
 
+        if pathIds := [str(path) for path in full_paths if not path.is_dir()]:
+            raise PluginError(
+                "The following paths do not exist or are not directories: "
+                + ", ".join(pathIds)
+            )
+
         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
 
-    def get_templates_dir(self, handler: str | None = None) -> Path:
+    def get_templates_dir(self, *args, **kwargs) -> Path:
         # use the python handler templates
         # (it assumes the python handler is installed)
         return super().get_templates_dir("python")
@@ -253,9 +274,6 @@ class MatlabHandler(BaseHandler):
             }
 
         # Map docstring options
-        final_config["show_submodules"] = config.get(
-            "show_subnamespaces", False
-        )
         final_config["show_docstring_attributes"] = config.get(
             "show_docstring_properties", True
         )
@@ -340,7 +358,10 @@ class MatlabHandler(BaseHandler):
             raise CollectionError("Empty identifier")
 
         final_config = ChainMap(config, self.default_config)  # type: ignore[arg-type]
-        return self.paths.resolve(identifier, config=final_config)
+        model = self.paths.resolve(identifier, config=final_config)
+        if model is None:
+            raise CollectionError(f"Identifier '{identifier}' not found")
+        return model
 
 
 def get_handler(

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.
 
@@ -141,13 +141,24 @@ class MatlabObject(Object):
             path_collection (PathCollection | None): The collection of paths related to the object.
             **kwargs: Arbitrary keyword arguments.
         """
-
         self.path_collection: "PathCollection | None" = path_collection
         lines_collection = (
             path_collection.lines_collection if path_collection is not None else None
         )
         super().__init__(*args, lines_collection=lines_collection, **kwargs)
 
+    @property
+    def namespaces(self) -> dict[str, "Namespace"]:
+        return {}
+
+    @property
+    def is_namespace(self) -> bool:
+        return False
+
+    @property
+    def is_folder(self) -> bool:
+        return False
+
     @property
     def canonical_path(self) -> str:
         """
@@ -156,7 +167,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 +176,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 +184,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 +194,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 +208,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):
@@ -444,6 +437,8 @@ class Property(MatlabMixin, Attribute, MatlabObject):
         self.SetAccess: AccessEnum = SetAccess
         self.getter: Function | None = None
 
+        self.extra["mkdocstrings"] = {"template": "property.html.jinja"}
+
     @property
     def Private(self) -> bool:
         private = self.Access != AccessEnum.public
@@ -559,19 +554,52 @@ 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.extra["mkdocstrings"] = {"template": "folder.html.jinja"}
+
+    def __repr__(self) -> str:
+        return f"Folder({self.filepath!r})"
+
+    @property
+    def namespaces(self) -> dict[str, "Namespace"]:
+        return {
+            name: member
+            for name, member in self.members.items()
+            if isinstance(member, Namespace)
+        }
+
+    @property
+    def is_folder(self) -> bool:
+        return True
+
+
 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:
         super().__init__(*args, **kwargs)
         self._access: AccessEnum = AccessEnum.public
+        self.extra["mkdocstrings"] = {"template": "namespace.html.jinja"}
 
     def __repr__(self) -> str:
         return f"Namespace({self.path!r})"
@@ -583,3 +611,7 @@ class Namespace(MatlabMixin, PathMixin, Module, MatlabObject):
             if self.filepath
             else False
         )
+
+    @property
+    def is_namespace(self) -> bool:
+        return True

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

@@ -0,0 +1,172 @@
+{#- Template for members (children) of an object.
+
+This template iterates on members of a given object and renders them.
+It can group members by category (attributes, classes, functions, modules) or render them in a flat list.
+
+Context:
+  obj (griffe.Object): The object to render.
+  config (dict): The configuration options.
+  root_members (bool): Whether the object is the root object.
+  heading_level (int): The HTML heading level to use.
+-#}
+
+{% if obj.all_members %}
+  {% block logs scoped %}
+    {#- Logging block.
+    
+    This block can be used to log debug messages, deprecation messages, warnings, etc.
+    -#}
+    {{ log.debug("Rendering children of " + obj.path) }}
+  {% endblock logs %}
+
+  <div class="doc doc-children">
+
+    {% if root_members %}
+      {% set members_list = config.members %}
+    {% else %}
+      {% set members_list = none %}
+    {% endif %}
+
+    {% if config.group_by_category %}
+
+      {% with %}
+
+        {% if config.show_category_heading %}
+          {% set extra_level = 1 %}
+        {% else %}
+          {% set extra_level = 0 %}
+        {% endif %}
+
+        {% with attributes = obj.attributes|filter_objects(
+            filters=config.filters,
+            members_list=members_list,
+            inherited_members=config.inherited_members,
+            keep_no_docstrings=config.show_if_no_docstring,
+          ) %}
+          {% if attributes %}
+            {% if config.show_category_heading %}
+              {% filter heading(heading_level, id=html_id ~ "-properties") %}Properties{% endfilter %}
+            {% endif %}
+            {% with heading_level = heading_level + extra_level %}
+              {% for attribute in attributes|order_members(config.members_order, members_list) %}
+                {% if members_list is not none or (not attribute.is_imported or attribute.is_public) %}
+                  {% include attribute|get_template with context %}
+                {% endif %}
+              {% endfor %}
+            {% endwith %}
+          {% endif %}
+        {% endwith %}
+
+        {% with classes = obj.classes|filter_objects(
+            filters=config.filters,
+            members_list=members_list,
+            inherited_members=config.inherited_members,
+            keep_no_docstrings=config.show_if_no_docstring,
+          ) %}
+          {% if classes %}
+            {% if config.show_category_heading %}
+              {% filter heading(heading_level, id=html_id ~ "-classes") %}Classes{% endfilter %}
+            {% endif %}
+            {% with heading_level = heading_level + extra_level %}
+              {% for class in classes|order_members(config.members_order, members_list) %}
+                {% if members_list is not none or (not class.is_imported or class.is_public) %}
+                  {% include class|get_template with context %}
+                {% endif %}
+              {% endfor %}
+            {% endwith %}
+          {% endif %}
+        {% endwith %}
+
+        {% with functions = obj.functions|filter_objects(
+            filters=config.filters,
+            members_list=members_list,
+            inherited_members=config.inherited_members,
+            keep_no_docstrings=config.show_if_no_docstring,
+          ) %}
+          {% if functions %}
+            {% if config.show_category_heading %}
+              {% filter heading(heading_level, id=html_id ~ "-functions") %}Functions{% endfilter %}
+            {% endif %}
+            {% with heading_level = heading_level + extra_level %}
+              {% for function in functions|order_members(config.members_order, members_list) %}
+                {% if not (obj.kind.value == "class" and function.name == "__init__" and config.merge_init_into_class) %}
+                  {% if members_list is not none or (not function.is_imported or function.is_public) %}
+                    {% include function|get_template with context %}
+                  {% endif %}
+                {% endif %}
+              {% endfor %}
+            {% endwith %}
+          {% endif %}
+        {% endwith %}
+
+        {% if config.show_submodules or obj.is_folder %}
+          {% with modules = obj.modules|filter_objects(
+              filters=config.filters,
+              members_list=members_list,
+              inherited_members=config.inherited_members,
+              keep_no_docstrings=config.show_if_no_docstring,
+            ) %}
+            {% if modules %}
+              {% if config.show_category_heading %}
+                {% filter heading(heading_level, id=html_id ~ "-namespaces") %}Modules{% endfilter %}
+              {% endif %}
+              {% with heading_level = heading_level + extra_level %}
+                {% for module in modules|order_members(config.members_order.alphabetical, members_list) %}
+                  {% if members_list is not none or (not module.is_alias or module.is_public) %}
+                    {% include module|get_template with context %}
+                  {% endif %}
+                {% endfor %}
+              {% endwith %}
+            {% endif %}
+          {% endwith %}
+        {% endif %}
+
+      {% endwith %}
+
+    {% else %}
+
+      {% for child in obj.all_members
+          |filter_objects(
+            filters=config.filters,
+            members_list=members_list,
+            inherited_members=config.inherited_members,
+            keep_no_docstrings=config.show_if_no_docstring,
+            )
+          |order_members(config.members_order, members_list)
+        %}
+
+        {% if not (obj.is_class and child.name == "__init__" and config.merge_init_into_class) %}
+
+          {% if members_list is not none or child.is_public %}
+            {% if child.is_attribute %}
+              {% with attribute = child %}
+                {% include attribute|get_template with context %}
+              {% endwith %}
+
+            {% elif child.is_class %}
+              {% with class = child %}
+                {% include class|get_template with context %}
+              {% endwith %}
+
+            {% elif child.is_function %}
+              {% with function = child %}
+                {% include function|get_template with context %}
+              {% endwith %}
+
+            {% elif (child.is_namespace and config.show_submodules) or obj.is_folder %}
+              {% with module = child %}
+                {% include module|get_template with context %}
+              {% endwith %}
+
+            {% endif %}
+          {% endif %}
+
+        {% endif %}
+
+      {% endfor %}
+
+    {% endif %}
+
+  </div>
+
+{% endif %}