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

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

@@ -52,12 +52,13 @@ jobs:
     - name: Check next semantic version
       run: |
         uv sync --dev
-        OUTPUT=$(uv run semantic-release --noop version --print)
-        echo "$OUTPUT"
-        if [ -z "$OUTPUT" ]; then
+        NEXT=$(uv run semantic-release --noop version --print-tag)
+        CURRENT=$(uv run semantic-release --noop version --print-last-released-tag)
+        echo "$NEXT"
+        if [ "$NEXT" = "$CURRENT" ]; then
           echo "comment=No release will be made." >> $GITHUB_ENV
         else
-          echo "comment=The next release will be v$OUTPUT" >> $GITHUB_ENV
+          echo "comment=The next release will be $NEXT" >> $GITHUB_ENV
         fi
 
     - name: Find Comment

{mkdocstrings_matlab-0.5.0 → mkdocstrings_matlab-0.7.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.15.2
+      uses: python-semantic-release/python-semantic-release@v9.16.0
       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.15.2
+      uses: python-semantic-release/publish-action@v9.16.0
       with:
         github_token: ${{ steps.app-token.outputs.token }}
         tag: ${{ steps.semantic-release.outputs.tag }}

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

@@ -1,6 +1,61 @@
 # CHANGELOG
 
 
+## v0.7.0 (2025-01-12)
+
+### Chores
+
+- **deps**: Update python-semantic-release/publish-action action to v9.16.0
+  ([#38](https://github.com/watermarkhu/mkdocstrings-matlab/pull/38),
+  [`fc404c4`](https://github.com/watermarkhu/mkdocstrings-matlab/commit/fc404c46af2830eaba288beb8635092174a21b3b))
+
+Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
+
+- **deps**: Update python-semantic-release/python-semantic-release action to v9.16.0
+  ([#39](https://github.com/watermarkhu/mkdocstrings-matlab/pull/39),
+  [`56e8f87`](https://github.com/watermarkhu/mkdocstrings-matlab/commit/56e8f877d357deeaee3eb6cf31bee2b064ee2438))
+
+Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
+
+Co-authored-by: Mark Shui Hu <watermarkhu@gmail.com>
+
+### Features
+
+- Folder modules ([#37](https://github.com/watermarkhu/mkdocstrings-matlab/pull/37),
+  [`81b551d`](https://github.com/watermarkhu/mkdocstrings-matlab/commit/81b551d794804212c18645926d58121cf556c79d))
+
+* remove redundant root object
+
+* feat: document folders
+
+* uv format
+
+* docs: update readme
+
+
+## v0.6.0 (2025-01-04)
+
+### Documentation
+
+- Add api documentation ([#33](https://github.com/watermarkhu/mkdocstrings-matlab/pull/33),
+  [`62632e8`](https://github.com/watermarkhu/mkdocstrings-matlab/commit/62632e8c5447125e5d2bfb58202d0fcd0de51ab9))
+
+- Add preview to docs index ([#32](https://github.com/watermarkhu/mkdocstrings-matlab/pull/32),
+  [`9289b11`](https://github.com/watermarkhu/mkdocstrings-matlab/commit/9289b118c7ca78bd3372a9559d140fa76ca89977))
+
+- Better docs ([#34](https://github.com/watermarkhu/mkdocstrings-matlab/pull/34),
+  [`bf97320`](https://github.com/watermarkhu/mkdocstrings-matlab/commit/bf973203343098a139afe571d37daa35b3b6359c))
+
+### Features
+
+- Show subnamespaces ([#36](https://github.com/watermarkhu/mkdocstrings-matlab/pull/36),
+  [`509e793`](https://github.com/watermarkhu/mkdocstrings-matlab/commit/509e7930f52f5656c9de1089daa4c0354ea170be))
+
+* add option show_subnamespaces
+
+* forward config
+
+
 ## v0.5.0 (2025-01-03)
 
 ### Features

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-matlab
-Version: 0.5.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
@@ -28,6 +28,8 @@ Requires-Dist: tree-sitter-matlab>=1.0.2
 Requires-Dist: tree-sitter>=0.23.2
 Description-Content-Type: text/markdown
 
+<!-- --8<-- [start:header] -->
+
 <h1 align="center">mkdocstrings-matlab</h1>
 
 <p align="center">A MATLAB handler for <a href="https://github.com/mkdocstrings/mkdocstrings"><i>mkdocstrings</i></a>.</p>
@@ -38,9 +40,8 @@ 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/). 
 
-## Installation
 
 You can install this handler by specifying it as a dependency:
 
@@ -53,6 +54,9 @@ dependencies = [
 ]
 ```
 
+<!-- --8<-- [end:header] -->
+<!-- --8<-- [start:footer] -->
+
 ## Features
 
 - **Data collection from source code**: collection of the object-tree and the docstrings is done thanks to
@@ -60,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.
+- **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. 
 
@@ -79,4 +83,6 @@ dependencies = [
   you can reference other objects within your docstrings, with the classic Markdown syntax:
   `[this object][namespace.subnamespace.object]` or directly with `[namespace.subnamespace.object][]`
 
-- **Source code display:** *mkdocstrings* can add a collapsible div containing the highlighted source code of the MATLAB object.
+- **Source code display:** *mkdocstrings* can add a collapsible div containing the highlighted source code of the MATLAB object.
+
+<!-- --8<-- [end:footer] -->

{mkdocstrings_matlab-0.5.0 → mkdocstrings_matlab-0.7.0}/README.md

@@ -1,3 +1,5 @@
+<!-- --8<-- [start:header] -->
+
 <h1 align="center">mkdocstrings-matlab</h1>
 
 <p align="center">A MATLAB handler for <a href="https://github.com/mkdocstrings/mkdocstrings"><i>mkdocstrings</i></a>.</p>
@@ -8,9 +10,8 @@
 [![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/). 
 
-## Installation
 
 You can install this handler by specifying it as a dependency:
 
@@ -23,6 +24,9 @@ dependencies = [
 ]
 ```
 
+<!-- --8<-- [end:header] -->
+<!-- --8<-- [start:footer] -->
+
 ## Features
 
 - **Data collection from source code**: collection of the object-tree and the docstrings is done thanks to
@@ -30,10 +34,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.
+- **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. 
 
@@ -49,4 +53,6 @@ dependencies = [
   you can reference other objects within your docstrings, with the classic Markdown syntax:
   `[this object][namespace.subnamespace.object]` or directly with `[namespace.subnamespace.object][]`
 
-- **Source code display:** *mkdocstrings* can add a collapsible div containing the highlighted source code of the MATLAB object.
+- **Source code display:** *mkdocstrings* can add a collapsible div containing the highlighted source code of the MATLAB object.
+
+<!-- --8<-- [end:footer] -->

mkdocstrings_matlab-0.7.0/docs/api.md

@@ -0,0 +1,16 @@
+
+!!! 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:
+      show_root_toc_entry: true
+      show_submodules: true
+      heading_level: 1
+      members:
+        - handler
+        - collect
+        - models
+        - treesitter

mkdocstrings_matlab-0.7.0/docs/index.md

@@ -0,0 +1,32 @@
+---
+hide:
+- feedback
+---
+
+--8<-- "README.md:header"
+
+## Preview 
+
+Let's us quickly see how auto-documentation works with mkdocstrings-matlab:
+
+```matlab title="Function making use of Argument Validation in namespace +mynamespace"
+--8<-- "docs/snippets/+mynamespace/typed_function.m"
+```
+
+<div class="result" markdown>
+
+![Image title](img/preview_dark.png#only-dark){ align=left width=400 }
+
+![Image title](img/preview_light.png#only-light){ align=left width=400 }
+
+Given the function above, the rendered documentation here is created from the following markdown document file,
+
+```markdown title="docs/api.md"
+::: mynamespace.typed_function
+    options:
+      parse_arguments: true
+```
+
+</div>
+
+--8<-- "README.md:footer"

mkdocstrings_matlab-0.7.0/docs/overrides/main.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  You're not viewing the latest version.
+  <a href="{{ '../' ~ base_url }}"> 
+    <strong>Click here to go to latest.</strong>
+  </a>
+{% endblock %}

mkdocstrings_matlab-0.7.0/docs/overrides/partials/toc-item.html

@@ -0,0 +1,20 @@
+<li class="md-nav__item">
+<a href="{{ toc_item.url }}" class="md-nav__link">
+    <span class="md-ellipsis">
+    {{ toc_item.title }}
+    </span>
+</a>
+
+<!-- Table of contents list -->
+{% if toc_item.children %}
+    <nav class="md-nav" aria-label="{{ toc_item.title | striptags }}">
+    <ul class="md-nav__list">
+        {% for toc_item in toc_item.children %}
+        {% if not page.meta.toc_depth or toc_item.level <= page.meta.toc_depth %}
+        {% include "partials/toc-item.html" %}
+        {% endif %}
+        {% endfor %}
+    </ul>
+    </nav>
+{% endif %}
+</li>

{mkdocstrings_matlab-0.5.0 → mkdocstrings_matlab-0.7.0}/docs/stylesheets/extra.css

@@ -3,6 +3,11 @@
 --md-primary-fg-color--dark:  #002f5b;
 }
 
+[data-md-color-scheme="matlab"] img[src$="#only-dark"],
+[data-md-color-scheme="matlab"] img[src$="#gh-dark-mode-only"] {
+  display: none; /* Hide dark images in light mode */
+}
+
 /* Custom admonition: preview */
 :root {
     --md-admonition-icon--preview: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M15.5 12a3.5 3.5 0 1 1-7 0 3.5 3.5 0 0 1 7 0Z"/><path d="M12 3.5c3.432 0 6.124 1.534 8.054 3.241 1.926 1.703 3.132 3.61 3.616 4.46a1.6 1.6 0 0 1 0 1.598c-.484.85-1.69 2.757-3.616 4.461-1.929 1.706-4.622 3.24-8.054 3.24-3.432 0-6.124-1.534-8.054-3.24C2.02 15.558.814 13.65.33 12.8a1.6 1.6 0 0 1 0-1.598c.484-.85 1.69-2.757 3.616-4.462C5.875 5.034 8.568 3.5 12 3.5ZM1.633 11.945a.115.115 0 0 0-.017.055c.001.02.006.039.017.056.441.774 1.551 2.527 3.307 4.08C6.691 17.685 9.045 19 12 19c2.955 0 5.31-1.315 7.06-2.864 1.756-1.553 2.866-3.306 3.307-4.08a.111.111 0 0 0 .017-.056.111.111 0 0 0-.017-.056c-.441-.773-1.551-2.527-3.307-4.08C17.309 6.315 14.955 5 12 5 9.045 5 6.69 6.314 4.94 7.865c-1.756 1.552-2.866 3.306-3.307 4.08Z"/></svg>');

{mkdocstrings_matlab-0.5.0 → mkdocstrings_matlab-0.7.0}/docs/usage/configuration/docstrings.md

@@ -1,3 +1,7 @@
+---
+toc_depth: 2
+---
+
 # Docstrings options
 
 ## `docstring_style`
@@ -607,12 +611,6 @@ plugins:
       show_docstring_namespaces: false
 ```
 
-```tree
-module/
-    __init__.py
-    submodule.py
-```
-
 --8<-- "docs/snippets/+module/module.md"
 
 ???+ preview

{mkdocstrings_matlab-0.5.0 → mkdocstrings_matlab-0.7.0}/docs/usage/configuration/general.md

@@ -1,3 +1,7 @@
+---
+toc_depth: 2
+---
+
 # General options
 
 ## `show_bases`

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

@@ -1,3 +1,7 @@
+---
+toc_depth: 2
+---
+
 # Headings options
 
 ## `heading_level`

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

@@ -1,3 +1,7 @@
+---
+toc_depth: 2
+---
+
 # Members options
 
 ## `members`
@@ -545,12 +549,69 @@ plugins:
         ```markdown
         ::: +mymembers
             options:
-              group_by_category: False
+              group_by_category: false
         ```
 
         ::: +mymembers
             options:
-              group_by_category: False
+              group_by_category: false
+
+## `show_subnamespaces`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+
+When rendering a namespace, show its subnamespaces recursively.
+
+This is false by default, because most of the time we render only one namespace per page, and when rendering a full package (a tree of namespaces and their members) on a single page, we quickly run out of [heading levels][heading_level].
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      matlab:
+        options:
+          show_subnamespaces: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: +matlab_namespace
+    options:
+      show_subnamespaces: false
+```
+
+--8<-- "docs/snippets/+module/module.md"
+
+???+ preview
+
+    === "With show subnamespaces"
+        
+        ```markdown
+        ::: +module
+            options:
+              show_subnamespaces: true
+        ```
+
+        ::: +module
+            options:
+              show_subnamespaces: true
+              show_docstring_namespaces: false
+              show_docstring_classes: false
+              show_docstring_functions: false
+
+    === "Without show subnamespaces"
+
+        ```markdown
+        ::: +module
+            options:
+              show_subnamespaces: false
+        ```
+
+        ::: +module
+            options:
+              show_subnamespaces: false
+              show_docstring_namespaces: false
+              show_docstring_classes: false
+              show_docstring_functions: false
 
 ## `summary`
 

{mkdocstrings_matlab-0.5.0 → mkdocstrings_matlab-0.7.0}/docs/usage/configuration/signatures.md

@@ -1,3 +1,7 @@
+---
+toc_depth: 2
+---
+
 # Signatures options
 
 ## `show_signature`

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

@@ -9,10 +9,12 @@ You can install this handler by specifying it as a dependency:
 # adapt to your dependencies manager
 [project]
 dependencies = [
-    "mkdocstrings-matlab>=0.3",
+    "mkdocstrings-matlab>=0.X.Y",
 ]
 ```
 
+## Configuration
+
 For *mkdocstrings* the default will be the Python handler. You can change the default handler,
 or explicitely set the MATLAB handler as default by defining the `default_handler`
 configuration option of `mkdocstrings` in `mkdocs.yml`:
@@ -21,8 +23,25 @@ configuration option of `mkdocstrings` in `mkdocs.yml`:
 plugins:
 - mkdocstrings:
     default_handler: matlab
+    matlab:
+        ...  # 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:
@@ -37,16 +56,17 @@ If another handler was defined as default handler, you can explicitely ask for t
 ::: path.to.object
     handler: matlab
 ```
+### Namespaces
 
 Entire [namespaces](https://mathworks.com/help/matlab/matlab_oop/namespaces.html) can be fully documented by prefixing the `+` character to the namespace that is to be documented. E.g. the following namespace 
 
-```
+```tree
 +mynamespace
-|- Contents.m
-|- readme.md
-|- myclass.m
-|- +subnamespace
-|  |- mfunction.m
+    Contents.m
+    readme.md
+    myclass.m
+    +subnamespace
+        mfunction.m
 ```
 
 is documented with:
@@ -55,8 +75,7 @@ is documented with:
 ::: +mynamespace
 ```
 
-The docstring of the namespace is taken from either the [`Contents.m`](https://mathworks.com/help/matlab/matlab_prog/create-a-help-summary-contents-m.html) or a `readme.md` that resides at the root level of the namespace, with `Contents.m` taking precedence over `readme.md`. 
-
+The docstring of the namespace is taken from either the [`Contents.m`](https://mathworks.com/help/matlab/matlab_prog/create-a-help-summary-contents-m.html) or a `readme.md` that resides at the root level of the namespace, with `Contents.m` taking precedence over `readme.md`.
 
 Documenting a nested namespace requires only a single prefixed `+` at the start of the fully resolved path, e.g. 
 
@@ -64,18 +83,50 @@ Documenting a nested namespace requires only a single prefixed `+` at the start
 ::: +mynamespace.subnamespace
 ```
 
-## Configuration
+### Folders
+
+Similarly to namepaces, all contents of a folder can be fully documented by specifying the relative path of a folder with respect to the `mkdocs.yml` config file. E.g. the following repository
+
+```tree
+src
+    module
+        myfunction.m
+        myClass.m
+        submodule
+            myfunction.m
+        +mynamespace
+            namespacefunction.m
+docs
+    index.md
+mkdocs.yml
+```
 
-When installed, the MATLAB handler becomes the default *mkdocstrings* handler. You can configure it in `mkdocs.yml`:
+is documented with:
 
-```yaml title="mkdocs.yml"
-plugins:
-- mkdocstrings:
-    handlers:
-      matlab:
-        ...  # the MATLAB handler configuration
+```markdown
+::: src/module
 ```
 
+In the case above the function `module/submodule/myfunction.m` overshadows the function `module/myfunction.m` on the MATLAB path. This means that in the global namespace myfunction will always call `module/submodule/myfunction.m`, which is the function to be documented by `::: myfunction`. 
+
+While this kind of behavior is strictly recommended against, mkdocstrings-matlab does support documenting the shadowed function by using its path. The file extension is now stricty required. 
+
+```markdown
+::: src/module/myfunction.m
+```
+
+!!! tip
+
+    A folder identifier must strictly contain the `/` character. For a folder `foo` that is in the same directory with `mkdocs.yml`, use `::: ./foo`. 
+
+!!! tip
+
+    If the `mkdocs.yml` lives inside of a subdirectly that does not contain source code, use relative paths e.g. `../src/module`. 
+
+!!! tip
+
+    Sub-selecting folder members are possible with the [members](./configuration/members.md) options. 
+
 ### Global-only options
 
 Some options are **global only**, and go directly under the handler's name.

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

@@ -1,9 +1,8 @@
 site_name: "mkdocstrings-matlab"
 site_description: "A MATLAB handler for mkdocstrings."
-# site_url: "https://mkdocstrings.github.io/python"
+site_url: "https://watermarkhu.nl/mkdocstrings-matlab"
 repo_url: "https://github.com/watermarkhu/mkdocstrings-matlab"
-repo_name: "watermarkhu/mkdocstrings-matlabn"
-site_dir: "site"
+repo_name: "watermarkhu/mkdocstrings-matlab"
 watch: [mkdocs.yml, README.md, src/mkdocstrings_handlers]
 copyright: Copyright © 2024 Mark Shui Hu
 edit_uri: edit/main/docs/
@@ -32,8 +31,9 @@ nav:
     - Numpy: usage/docstrings/numpy.md
     - Sphinx: usage/docstrings/sphinx.md
 # # defer to gen-files + literate-nav
-# - API reference:
-#   - mkdocstrings-python: reference/
+- API reference:
+  - mkdocstrings_handlers:
+    - matlab: api.md
 # - Development:
 #   - Contributing: contributing.md
 #   - Code of Conduct: code_of_conduct.md
@@ -48,6 +48,7 @@ nav:
 theme:
   name: material
   logo: logo.svg
+  custom_dir: docs/overrides
   features:
   - announce.dismiss
   - content.action.edit
@@ -123,17 +124,13 @@ markdown_extensions:
     custom_checkbox: true
 - toc:
     permalink: "¤"
-    toc_depth: 2
+    toc_depth: 3
+
 plugins:
 - autorefs
 - search
 - markdown-exec
 - callouts
-# - gen-files:
-#     scripts:
-#     - scripts/gen_ref_nav.py
-# - literate-nav:
-#     nav_file: SUMMARY.md
 - mkdocs-material-matlab
 - mkdocstrings:
     default_handler: matlab
@@ -177,13 +174,9 @@ plugins:
           show_signature_annotations: false
           separate_signature: false 
       python:
-        paths: [src, docs/snippets]
+        paths: [src]
         import:
         - https://docs.python.org/3/objects.inv
-        - https://mkdocstrings.github.io/objects.inv
-        - https://mkdocstrings.github.io/autorefs/objects.inv
-        - https://mkdocstrings.github.io/griffe/objects.inv
-        - https://python-markdown.github.io/objects.inv
         options:
           docstring_options:
             ignore_init_summary: true
@@ -193,7 +186,6 @@ plugins:
           inherited_members: true
           merge_init_into_class: true
           parameter_headings: true
-          preload_modules: [mkdocstrings]
           relative_crossrefs: true
           scoped_crossrefs: true
           separate_signature: true
@@ -220,3 +212,7 @@ plugins:
     plugins:
     - typeset
 
+extra:
+  version:
+    provider: mike
+    alias: true

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

@@ -1,11 +1,11 @@
 [project]
 name = "mkdocstrings-matlab"
-version = "0.5.0"
+version = "0.7.0"
 description = "A MATLAB handler for mkdocstrings"
 authors = [
     { name = "Mark Hu", email = "watermarkhu@gmail.com" }
 ]
-license =  { text = "ISC" }
+license =  { text = "MIT" }
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [