mkdocstrings-matlab 0.7.0__tar.gz → 0.8.0__tar.gz

{mkdocstrings_matlab-0.7.0 → mkdocstrings_matlab-0.8.0}/.github/workflows/qualify.yaml

@@ -10,6 +10,7 @@ on:
       - synchronize
       - labeled
       - unlabeled
+      - edited
     branches:
       - main
 
@@ -38,11 +39,16 @@ jobs:
       uses: actions/checkout@v4
       with: 
         fetch-depth: 0
-        ref: ${{ github.sha }}
+        ref: main
 
-    - name: Force correct release branch on workflow sha
+    - name: Create fake commit with PR title
       run: |
-        git checkout -B ${{ github.ref_name }} ${{ github.sha }}
+        git config --global user.name '${{ steps.app-token.outputs.app-slug }}[bot]'
+        git config --global user.email '${{ steps.get-user-id.outputs.user-id }}+${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com'
+        git switch -c temp-${{ github.run_id }}
+        touch temp.txt
+        git add temp.txt
+        git commit -m "${{ github.event.pull_request.title }}"
 
     - name: Install the latest version of uv
       uses: astral-sh/setup-uv@v5

{mkdocstrings_matlab-0.7.0 → mkdocstrings_matlab-0.8.0}/.github/workflows/release.yaml

@@ -55,7 +55,7 @@ jobs:
 
     - name: Update version and changelogs
       id: semantic-release
-      uses: python-semantic-release/python-semantic-release@v9.16.0
+      uses: python-semantic-release/python-semantic-release@v9.16.1
       with: 
         build: false
         changelog: true
@@ -81,7 +81,7 @@ jobs:
     - name: Publish package distributions to GitHub Releases
       if: steps.semantic-release.outputs.released == 'true'
       id: publish-dist
-      uses: python-semantic-release/publish-action@v9.16.0
+      uses: python-semantic-release/publish-action@v9.16.1
       with:
         github_token: ${{ steps.app-token.outputs.token }}
         tag: ${{ steps.semantic-release.outputs.tag }}

mkdocstrings_matlab-0.8.0/.github/workflows/update-templates.yaml

@@ -0,0 +1,48 @@
+name: Update template copies
+
+on:
+  pull_request:
+    types: 
+      - opened
+      - synchronize
+      - reopened
+      - edited
+
+permissions:
+  contents: write
+
+jobs:
+  update-templates:
+    runs-on: ubuntu-latest
+    if: contains(github.event.pull_request.title, 'mkdocstrings-python')
+
+    steps:
+    
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with: 
+          fetch-depth: 0
+          ref: ${{ github.sha }}
+
+      - name: Force correct release branch on workflow sha
+        run: |
+          git checkout -B ${{ github.ref_name }} ${{ github.sha }}
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Run script
+        run: |
+          uv sync 
+          uv run python scripts/copy_and_update_python_templates.py
+
+      - name: Commit changes
+        continue-on-error: true # Ignore if there are no changes
+        run: |
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git add .
+          git commit -m "Update templates"
+          git push origin ${{ github.ref_name }}

{mkdocstrings_matlab-0.7.0 → mkdocstrings_matlab-0.8.0}/.gitignore

@@ -122,6 +122,7 @@ celerybeat.pid
 *.sage.py
 
 # Environments
+uv.lock
 .env
 .venv
 env/

{mkdocstrings_matlab-0.7.0 → mkdocstrings_matlab-0.8.0}/CHANGELOG.md

@@ -1,6 +1,14 @@
 # CHANGELOG
 
 
+## v0.8.0 (2025-01-13)
+
+### Features
+
+- Update dependencies ([#46](https://github.com/watermarkhu/mkdocstrings-matlab/pull/46),
+  [`03229a2`](https://github.com/watermarkhu/mkdocstrings-matlab/commit/03229a2e7ef8ee46dc680b676a796ae38c6617b7))
+
+
 ## v0.7.0 (2025-01-12)
 
 ### Chores

{mkdocstrings_matlab-0.7.0 → mkdocstrings_matlab-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-matlab
-Version: 0.7.0
+Version: 0.8.0
 Summary: A MATLAB handler for mkdocstrings
 Author-email: Mark Hu <watermarkhu@gmail.com>
 License: MIT
@@ -21,11 +21,11 @@ Classifier: Topic :: Software Development :: Documentation
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: charset-normalizer>=3.3.2
+Requires-Dist: charset-normalizer==3.4.1
 Requires-Dist: mkdocstrings-python==1.13.0
 Requires-Dist: mkdocstrings==0.27.0
-Requires-Dist: tree-sitter-matlab>=1.0.2
-Requires-Dist: tree-sitter>=0.23.2
+Requires-Dist: tree-sitter-matlab==1.0.3
+Requires-Dist: tree-sitter==0.23.2
 Description-Content-Type: text/markdown
 
 <!-- --8<-- [start:header] -->

{mkdocstrings_matlab-0.7.0 → mkdocstrings_matlab-0.8.0}/docs/api.md

@@ -1,8 +1,4 @@
 
-!!! note
-
-    Due to that for the documentation of mkdocstrings-matlab both the MATLAB and the Python handler are loaded, the symbols shown for Python objects will be incorrect (see [Configuration](usage/index.md#configuration)). 
-
 ::: mkdocstrings_handlers.matlab
     handler: python
     options:

{mkdocstrings_matlab-0.7.0 → mkdocstrings_matlab-0.8.0}/docs/usage/configuration/headings.md

@@ -553,13 +553,17 @@ plugins:
     === "With symbol type in headings"
 
         ```markdown
-        ::: +mynamespace
+        ::: docs/snippets
             options:
+              members:
+                - mynamespace
               show_symbol_type_heading: true
         ```
 
-        ::: +mynamespace
+        ::: docs/snippets
             options:
+              members: 
+                - mynamespace
               show_symbol_type_heading: true
               show_docstring_input_arguments: false
               show_docstring_output_arguments: false
@@ -567,13 +571,17 @@ plugins:
     === "Without symbol type in headings"
 
         ```markdown
-        ::: +mynamespace
+        ::: docs/snippets
             options:
+              members:
+                - mynamespace
               show_symbol_type_heading: false
         ```
 
-        ::: +mynamespace
+        ::: docs/snippets
             options:
+              members:
+                - mynamespace
               show_symbol_type_heading: false
               show_docstring_input_arguments: false
               show_docstring_output_arguments: false
@@ -586,11 +594,12 @@ plugins:
 Show the symbol type in the Table of Contents.
 
 This option will prefix items in the ToC 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-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)"
@@ -603,7 +612,7 @@ 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. 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. 
+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)"
@@ -617,12 +626,13 @@ plugins:
     === "With symbol type in ToC"
 
         <ul style="list-style: none;">
-          <li><code class="doc-symbol doc-symbol-module"></code> namespace</li>
+          <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-function"></code> function</li>
           <li><code class="doc-symbol doc-symbol-class"></code> Class
             <ul style="list-style: none;">
               <li><code class="doc-symbol doc-symbol-method"></code> method</li>
-              <li><code class="doc-symbol doc-symbol-attribute"></code> property</li>
+              <li><code class="doc-symbol doc-symbol-property"></code> property</li>
             </ul>
           </li>
         </ul>
@@ -630,6 +640,7 @@ plugins:
     === "Without symbol type in ToC"
 
         <ul style="list-style: none;">
+          <li>folder</li>
           <li>namespace</li>
           <li>function</li>
           <li>Class

{mkdocstrings_matlab-0.7.0 → mkdocstrings_matlab-0.8.0}/docs/usage/configuration/members.md

@@ -700,11 +700,6 @@ plugins:
               summary:
                 functions: true
 
-!!! warning
-
-    In the summary, the title of the properties summary will be *attributes*, and the title of the namespaces summary will be *modules*. This is due to mkdocstrings-matlab's dependency on mkdocstrings-python. For now, mkdocstrings-matlab does not implement its own Jinja templates for rendering, leading to these summary titles. 
-
-
 ## `show_labels`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**

{mkdocstrings_matlab-0.7.0 → mkdocstrings_matlab-0.8.0}/docs/usage/index.md

@@ -27,21 +27,14 @@ plugins:
         ...  # the MATLAB handler configuration
 ```
 
-When using the [material](https://squidfunk.github.io/mkdocs-material) theme, it is best to also configure the `mkdocs_material_matlab` plugin. This additional plugin, which is installed together with mkdocstrings-matlab, will overrule the symbols shown with [`show_symbol_type_heading`][] and [`show_symbol_type_toc`][] to show the correct symbols as per MATLAB nomenclature. 
-
 ```yaml title="mkdocs.yml"
 plugins:
-- mkdocs_material_matlab
 - mkdocstrings:
     default_handler: matlab
     matlab:
         ...  # the MATLAB handler configuration
 ```
 
-??? warning "I want to document both MATLAB and Python"
-
-    The `mkdocs_material_matlab` plugin will also change the symbols for the Python handler. This means that Python modules will not be tagged with symbol `mod` but `name` (namespace), and attributes are not tagged with symbol `attr` but `prop` (property). 
-
 ## Injecting documentation
 
 With the MATLAB handler installed and configured as default handler, you can inject documentation for a module, class, function, or any other MATLAB object with *mkdocstrings*' [autodoc syntax], in your Markdown pages:

{mkdocstrings_matlab-0.7.0 → mkdocstrings_matlab-0.8.0}/mkdocs.yml

@@ -127,11 +127,10 @@ markdown_extensions:
     toc_depth: 3
 
 plugins:
+- callouts
 - autorefs
 - search
 - markdown-exec
-- callouts
-- mkdocs-material-matlab
 - mkdocstrings:
     default_handler: matlab
     handlers:
@@ -201,16 +200,13 @@ plugins:
           summary: true
           unwrap_annotated: true
 
+- minify:
+    minify_html: !ENV [DEPLOY, false]
+
 - git-revision-date-localized:
     enabled: !ENV [DEPLOY, false]
     enable_creation_date: true
     type: timeago
-- minify:
-    minify_html: !ENV [DEPLOY, false]
-- group:
-    enabled: !ENV [MATERIAL_INSIDERS, false]
-    plugins:
-    - typeset
 
 extra:
   version:

{mkdocstrings_matlab-0.7.0 → mkdocstrings_matlab-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocstrings-matlab"
-version = "0.7.0"
+version = "0.8.0"
 description = "A MATLAB handler for mkdocstrings"
 authors = [
     { name = "Mark Hu", email = "watermarkhu@gmail.com" }
@@ -10,10 +10,10 @@ readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
     "mkdocstrings==0.27.0",
-    "mkdocstrings-python==1.13.0",  # Later versions will currently break 
-    "charset-normalizer>=3.3.2",
-    "tree-sitter>=0.23.2",
-    "tree-sitter-matlab>=1.0.2",
+    "mkdocstrings-python==1.13.0",
+    "charset-normalizer==3.4.1",
+    "tree-sitter==0.23.2",
+    "tree-sitter-matlab==1.0.3",
 ]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -44,19 +44,13 @@ managed = true
 allow-direct-references = true
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/mkdocstrings_handlers", "src/mkdocs_material_matlab"]
-
-[project.entry-points."mkdocs.plugins"]
-mkdocs-material-matlab = "mkdocs_material_matlab:MkdocsMaterialMatlabPlugin"
+packages = ["src/mkdocstrings_handlers"]
 
 [dependency-groups]
 docs = [
     "mkdocs-material>=9.5.33",
     "markdown-exec>=1.10.0",
     "mkdocs-callouts>=1.15.0",
-    "mkdocs-with-pdf>=0.9.3",
-    "mkdocs-gen-files>=0.5.0",
-    "mkdocs-literate-nav>=0.6.1",
     "mkdocs-git-revision-date-localized-plugin>=1.3.0",
     "mkdocs-minify-plugin>=0.8.0",
     "mike>=2.1.3",

mkdocstrings_matlab-0.8.0/scripts/copy_and_update_python_templates.py

@@ -0,0 +1,121 @@
+"""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
+
+# Get the templates directory of the python handler
+pythonHandler = PythonHandler("python", "material")
+templatesDir = pythonHandler.get_templates_dir()
+targetDir = (
+    Path(__file__).parent.parent
+    / "src"
+    / "mkdocstrings_handlers"
+    / "matlab"
+    / "templates"
+)
+
+
+def copy_template(
+    sourcePath: str,
+    targetPath: str,
+    mapping: dict[str, str] = {},
+    theme: str = "material",
+):
+    sourceFile = templatesDir / theme / sourcePath
+    targetFile = targetDir / theme / targetPath
+    content = sourceFile.read_text()
+    pattern = re.compile(
+        "|".join([re.escape(k) for k in sorted(mapping, key=len, reverse=True)]),
+        flags=re.DOTALL,
+    )
+    content = pattern.sub(lambda x: mapping[x.group(0)], content)
+    targetFile.write_text(content)
+
+    return (targetFile, content)
+
+
+# Copy the namespace and module templates
+copy_template(
+    "_base/module.html.jinja",
+    "folder.html.jinja",
+    {"doc-symbol-module": "doc-symbol-folder"},
+)
+copy_template(
+    "_base/module.html.jinja",
+    "namespace.html.jinja",
+    {"doc-symbol-module": "doc-symbol-namespace"},
+)
+
+# Copy the property template
+copy_template(
+    "_base/attribute.html.jinja",
+    "property.html.jinja",
+    {"doc-symbol-attribute": "doc-symbol-property"},
+)
+
+# Copy the summary modules template
+copy_template(
+    "_base/summary.html.jinja",
+    "summary.html.jinja",
+    {
+        "summary/modules": "summary/namespaces",
+        "summary/attributes": "summary/properties",
+    },
+)
+
+
+## Copy the summary properties template
+copy_template(
+    "_base/summary/attributes.html.jinja",
+    "summary/properties.html.jinja",
+    {
+        "docstring/attributes": "docstring/properties",
+        "Summary of attributes": "Summary of properties",
+    },
+)
+copy_template(
+    "_base/docstring/attributes.html.jinja",
+    "docstring/properties.html.jinja",
+    {
+        'lang.t("Attributes:")': '"Properties:"',
+        'lang.t("ATTRIBUTE")': '"PROPERTY:"',
+        " attributes ": " properties ",
+        '"Attributes"': '"Properties"',
+    },
+)
+
+## Copy the summary namespaces template
+copy_template(
+    "_base/summary/modules.html.jinja",
+    "summary/namespaces.html.jinja",
+    {
+        "docstring/modules": "docstring/namespaces",
+        "Summary of modules": "Summary of namespaces",
+    },
+)
+copy_template(
+    "_base/docstring/modules.html.jinja",
+    "docstring/namespaces.html.jinja",
+    {
+        'lang.t("Modules:")': '"Namespaces:"',
+        'lang.t("MODULE")': '"NAMESPACE:"',
+        " modules ": " namespaces ",
+        '"Modules"': '"Namespaces"',
+    },
+)
+
+## Copy children template
+copy_template(
+    "_base/children.html.jinja",
+    "children.html.jinja",
+    {
+        "-attributes": "-properties",
+        "Attributes": "Properties",
+        "-modules": "-namespaces",
+        "Modules": "Modules",
+        "{% if config.show_submodules %}": "{% if config.show_submodules or obj.is_folder %}",
+        "{% elif child.is_module and config.show_submodules %}": "{% elif (child.is_namespace and config.show_submodules) or obj.is_folder %}",
+    },
+)

{mkdocstrings_matlab-0.7.0 → mkdocstrings_matlab-0.8.0}/src/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,7 +178,16 @@ 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
@@ -182,13 +196,19 @@ class MatlabHandler(BaseHandler):
             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, 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")
@@ -254,7 +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
         )
@@ -339,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_matlab-0.7.0 → mkdocstrings_matlab-0.8.0}/src/mkdocstrings_handlers/matlab/models.py

@@ -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:
         """
@@ -426,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
@@ -554,10 +567,22 @@ class Folder(MatlabMixin, PathMixin, Module, MatlabObject):
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
-        self.labels = {"Folder"}
+        self.extra["mkdocstrings"] = {"template": "folder.html.jinja"}
 
     def __repr__(self) -> str:
-        return f"Folder({self.path!r})"
+        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):
@@ -574,6 +599,7 @@ class Namespace(MatlabMixin, PathMixin, Module, MatlabObject):
     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})"
@@ -585,3 +611,7 @@ class Namespace(MatlabMixin, PathMixin, Module, MatlabObject):
             if self.filepath
             else False
         )
+
+    @property
+    def is_namespace(self) -> bool:
+        return True