mkdocstrings-matlab 1.0.8__tar.gz → 1.0.9__tar.gz

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/.github/workflows/docs.yaml

@@ -58,14 +58,21 @@ jobs:
           git config --global user.email 41898282+github-actions[bot]@users.noreply.github.com
   
       - name: Build documentation with mike
+        shell: bash
         env:
           PUSH_DEPLOY: ${{ fromJson(inputs.push) && '--push' || '' }}
-        run: >
-          uv run mike deploy ${PUSH_DEPLOY}
-          --update-aliases
-          --branch gh-pages
-          --alias-type symlink
-          ${{ inputs.version }} ${{ inputs.alias }}
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ inputs.version }}
+        run: |
+          if [[ $VERSION =~ ^v([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
+            VERSION="v${BASH_REMATCH[1]}.${BASH_REMATCH[2]}.*"
+            echo "Patching version "${{ inputs.version }}" to $VERSION"
+          fi
+          uv run mike deploy ${PUSH_DEPLOY} \
+            --update-aliases \
+            --branch gh-pages \
+            --alias-type symlink \
+            "$VERSION" "${{ inputs.alias }}"
       
       - name: Set default alias for mike 
         if: ${{ fromJson(inputs.set-default) }}

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/PKG-INFO

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

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/pyproject.toml

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

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/src/mkdocstrings_handlers/matlab/config.py

@@ -7,6 +7,7 @@ import sys
 from dataclasses import field, fields
 from typing import TYPE_CHECKING, Annotated, Any, Literal
 
+from griffe._internal.docstrings.parsers import DocstringStyle
 from mkdocstrings import get_logger
 
 # YORE: EOL 3.10: Replace block with line 2.
@@ -358,12 +359,12 @@ class MatlabInputOptions:
     ] = "table"
 
     docstring_style: Annotated[
-        Literal["google", "numpy", "sphinx"] | None,
+        DocstringStyle | None,
         Field(
             group="docstrings",
-            description="The docstring style to use: `google`, `numpy`, `sphinx`, or `None`.",
+            description="The docstring style to use: `auto`, `google`, `numpy`, `sphinx`, or `None`.",
         ),
-    ] = "google"
+    ] = "auto"
 
     parse_arguments: Annotated[
         bool,

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/src/mkdocstrings_handlers/matlab/handler.py

@@ -169,6 +169,7 @@ class MatlabHandler(BaseHandler):
         self.env.filters["stash_crossref"] = rendering.do_stash_crossref
         self.env.filters["get_template"] = rendering.do_get_template
         self.env.filters["function_docstring"] = rendering.do_function_docstring
+        self.env.filters["parse_docstring"] = rendering.do_parse_docstring
         self.env.filters["as_properties_section"] = rendering.do_as_properties_section
         self.env.filters["as_functions_section"] = rendering.do_as_functions_section
         self.env.filters["as_classes_section"] = rendering.do_as_classes_section

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/src/mkdocstrings_handlers/matlab/rendering.py

@@ -14,6 +14,7 @@ from typing import TYPE_CHECKING, Any, Callable, ClassVar, Literal
 from griffe import (
     AliasResolutionError,
     CyclicAliasError,
+    Docstring,
     DocstringAttribute,
     DocstringClass,
     DocstringFunction,
@@ -32,6 +33,7 @@ from griffe._internal.docstrings.models import (
     DocstringSectionParameters,
     DocstringSectionReturns,
 )
+from griffe._internal.docstrings.parsers import DocstringStyle, parse
 from jinja2 import pass_context
 from markupsafe import Markup
 from maxx.enums import ArgumentKind
@@ -612,17 +614,30 @@ def do_as_namespaces_section(
     )
 
 
+def do_parse_docstring(
+    docstring: Docstring | None,
+    docstring_style: DocstringStyle,
+    docstring_options: dict[str, Any] | None,
+) -> list[DocstringSection]:
+    if docstring is None:
+        return []
+    options = docstring_options or {}
+    return parse(docstring, docstring_style, **options)
+
+
 def do_function_docstring(
     function: Function,
     parse_arguments: bool,
     show_docstring_input_arguments: bool,
     show_docstring_name_value_arguments: bool,
     show_docstring_output_arguments: bool,
+    docstring_style: DocstringStyle,
+    docstring_options: dict[str, Any] | None,
 ) -> list[DocstringSection]:
     if function.docstring is None:
         return []
 
-    docstring_sections = [section for section in function.docstring.parsed]
+    docstring_sections = do_parse_docstring(function.docstring, docstring_style, docstring_options)
     if not parse_arguments or not (
         show_docstring_input_arguments
         or show_docstring_name_value_arguments

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/src/mkdocstrings_handlers/matlab/templates/material/class.html.jinja

@@ -154,7 +154,7 @@ Context:
 
           This block renders the docstring for the class.
           -#}
-          {% with docstring_sections = class.docstring.parsed %}
+          {% with docstring_sections = class.docstring | parse_docstring(config.docstring_style, config.docstring_options) %}
             {% include "docstring.html.jinja" with context %}
           {% endwith %}
           {% if config.merge_constructor_into_class and class.constructor %}
@@ -163,7 +163,7 @@ Context:
             {% with check_members = all_members if (config.inherited_members is true or (config.inherited_members is iterable and class.constructor.name in config.inherited_members)) else class.members %}
               {% if class.constructor.name in check_members and class.constructor.has_docstring %}
                 {% with function = class.constructor %}
-                  {% with obj = function, docstring_sections = function | function_docstring(config.parse_arguments, config.show_docstring_input_arguments, config.show_docstring_name_value_arguments, config.show_docstring_output_arguments) %}
+                  {% with obj = function, docstring_sections = function | function_docstring(config.parse_arguments, config.show_docstring_input_arguments, config.show_docstring_name_value_arguments, config.show_docstring_output_arguments, config.docstring_style, config.docstring_options) %}
                     {% include "docstring.html.jinja" with context %}
                   {% endwith %}
                 {% endwith %}

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/src/mkdocstrings_handlers/matlab/templates/material/folder.html.jinja

@@ -79,7 +79,7 @@ Context:
 
           This block renders the docstring for the folder.
           -#}
-          {% with docstring_sections = folder.docstring.parsed %}
+          {% with docstring_sections = folder.docstring | parse_docstring(config.docstring_style, config.docstring_options) %}
             {% include "docstring.html.jinja" with context %}
           {% endwith %}
         {% endblock docstring %}

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/src/mkdocstrings_handlers/matlab/templates/material/function.html.jinja

@@ -114,7 +114,7 @@ Context:
 
           This block renders the docstring for the function.
           -#}
-          {% with docstring_sections = function | function_docstring(config.parse_arguments, config.show_docstring_input_arguments, config.show_docstring_name_value_arguments, config.show_docstring_output_arguments) %}
+          {% with docstring_sections = function | function_docstring(config.parse_arguments, config.show_docstring_input_arguments, config.show_docstring_name_value_arguments, config.show_docstring_output_arguments, config.docstring_style, config.docstring_options) %}
             {% include "docstring.html.jinja" with context %}
           {% endwith %}
         {% endblock docstring %}

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/src/mkdocstrings_handlers/matlab/templates/material/namespace.html.jinja

@@ -82,7 +82,7 @@ Context:
 
           This block renders the docstring for the namespace.
           -#}
-          {% with docstring_sections = namespace.docstring.parsed %}
+          {% with docstring_sections = namespace.docstring | parse_docstring(config.docstring_style, config.docstring_options) %}
             {% include "docstring.html.jinja" with context %}
           {% endwith %}
         {% endblock docstring %}

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/src/mkdocstrings_handlers/matlab/templates/material/property.html.jinja

@@ -109,7 +109,7 @@ Context:
 
           This block renders the docstring for the property.
           -#}
-          {% with docstring_sections = property.docstring.parsed %}
+          {% with docstring_sections = property.docstring | parse_docstring(config.docstring_style, config.docstring_options) %}
             {% include "docstring.html.jinja" with context %}
           {% endwith %}
         {% endblock docstring %}

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/src/mkdocstrings_handlers/matlab/templates/material/script.html.jinja

@@ -85,7 +85,7 @@ Context:
           
           This block renders the docstring for the script.
           -#}
-          {% with docstring_sections = script.docstring.parsed %}
+          {% with docstring_sections = script.docstring | parse_docstring(config.docstring_style, config.docstring_options) %}
             {% include "docstring.html.jinja" with context %}
           {% endwith %}
         {% endblock docstring %}

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/src/mkdocstrings_handlers/matlab/templates/material/summary/classes.html.jinja

@@ -7,7 +7,7 @@
   -#}
 {% endblock logs %}
 
-{% if not obj.docstring.parsed | selectattr("kind.value", "eq", "classes") | list %}
+{% if not obj.docstring | parse_docstring(config.docstring_style, config.docstring_options) | selectattr("kind.value", "eq", "classes") | list %}
   {% with section = obj.classes
       |filter_objects(
         filters=config.filters,

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/src/mkdocstrings_handlers/matlab/templates/material/summary/functions.html.jinja

@@ -7,7 +7,7 @@
   -#}
 {% endblock logs %}
 
-{% if not obj.docstring.parsed | selectattr("kind.value", "eq", "functions") | list %}
+{% if not obj.docstring | parse_docstring(config.docstring_style, config.docstring_options) | selectattr("kind.value", "eq", "functions") | list %}
   {% with section = obj.functions
       |filter_objects(
         filters=config.filters,

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/src/mkdocstrings_handlers/matlab/templates/material/summary/namespaces.html.jinja

@@ -7,7 +7,7 @@
   -#}
 {% endblock logs %}
 
-{% if not obj.docstring.parsed | selectattr("kind.value", "eq", "modules") | list %}
+{% if not obj.docstring | parse_docstring(config.docstring_style, config.docstring_options) | selectattr("kind.value", "eq", "modules") | list %}
   {% with section = obj.modules
       |filter_objects(
         filters=config.filters,

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/src/mkdocstrings_handlers/matlab/templates/material/summary/properties.html.jinja

@@ -7,7 +7,7 @@
   -#}
 {% endblock logs %}
 
-{% if not obj.docstring.parsed | selectattr("kind.value", "eq", "properties") | list %}
+{% if not obj.docstring | parse_docstring(config.docstring_style, config.docstring_options) | selectattr("kind.value", "eq", "properties") | list %}
   {% with section = obj.properties
       |filter_objects(
         filters=config.filters,

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/test/snapshots/__init__.py

@@ -6,16 +6,24 @@ register_format_alias(".html", ".txt")
 
 signature_show = snapshot(
     {
-        (("identifier", "classFolder"), ("show_signature", True)): external("9bdbcd111c2c*.html"),
-        (("identifier", "moduleClass"), ("show_signature", False)): external("0dc4897f65cf*.html"),
-        (("identifier", "classFolder"), ("show_signature", False)): external("92b0fb53d670*.html"),
-        (("identifier", "moduleClass"), ("show_signature", True)): external("7589cda3f729*.html"),
         (("identifier", "module_function"), ("show_signature", True)): external(
             "da2df1c0e3d9*.html"
         ),
         (("identifier", "module_function"), ("show_signature", False)): external(
             "d3f96b8d107b*.html"
         ),
+        (("identifier", "moduleClass"), ("show_signature", True)): external(
+            "hash:7589cda3f729*.html"
+        ),
+        (("identifier", "moduleClass"), ("show_signature", False)): external(
+            "hash:0dc4897f65cf*.html"
+        ),
+        (("identifier", "classFolder"), ("show_signature", True)): external(
+            "hash:9bdbcd111c2c*.html"
+        ),
+        (("identifier", "classFolder"), ("show_signature", False)): external(
+            "hash:92b0fb53d670*.html"
+        ),
     }
 )
 
@@ -144,17 +152,27 @@ toc = snapshot(
 
 members = snapshot(
     {
-        (("filters", False), ("members", True), ("members_order", "alphabetical")): external(
-            "hash:cd9476a4d9e9*.html"
-        ),
         (("filters", False), ("members", False), ("members_order", "source")): external(
             "hash:8aeecc7e575c*.html"
         ),
         (("filters", False), ("members", False), ("members_order", "alphabetical")): external(
             "hash:6fe7ef6969cc*.html"
         ),
-        (("filters", False), ("members", True), ("members_order", "source")): external(
-            "hash:7130f7ac88be*.html"
+        (
+            ("filters", ("!method1",)),
+            ("members", False),
+            ("members_order", "alphabetical"),
+        ): external("hash:b360046d413f*.html"),
+        (("filters", ("!method1",)), ("members", False), ("members_order", "source")): external(
+            "hash:abc017eefa9d*.html"
+        ),
+        (
+            ("filters", ("method*",)),
+            ("members", False),
+            ("members_order", "alphabetical"),
+        ): external("hash:bcbbdfbe7a0f*.html"),
+        (("filters", ("method*",)), ("members", False), ("members_order", "source")): external(
+            "hash:b42f328b72ea*.html"
         ),
         (
             ("filters", ("!method1",)),
@@ -174,14 +192,6 @@ members = snapshot(
         (("filters", ("!method1",)), ("members", True), ("members_order", "source")): external(
             "hash:7f035d40c198*.html"
         ),
-        (
-            ("filters", ("!method1",)),
-            ("members", False),
-            ("members_order", "alphabetical"),
-        ): external("hash:b360046d413f*.html"),
-        (("filters", ("!method1",)), ("members", False), ("members_order", "source")): external(
-            "hash:abc017eefa9d*.html"
-        ),
         (
             ("filters", ("method*",)),
             ("members", ("method1",)),
@@ -198,14 +208,6 @@ members = snapshot(
         (("filters", ("method*",)), ("members", True), ("members_order", "source")): external(
             "hash:568c966787a0*.html"
         ),
-        (
-            ("filters", ("method*",)),
-            ("members", False),
-            ("members_order", "alphabetical"),
-        ): external("hash:bcbbdfbe7a0f*.html"),
-        (("filters", ("method*",)), ("members", False), ("members_order", "source")): external(
-            "hash:b42f328b72ea*.html"
-        ),
         (
             ("filters", False),
             ("members", ("method1",)),
@@ -214,6 +216,12 @@ members = snapshot(
         (("filters", False), ("members", ("method1",)), ("members_order", "source")): external(
             "hash:01ca7e807eab*.html"
         ),
+        (("filters", False), ("members", True), ("members_order", "alphabetical")): external(
+            "hash:cd9476a4d9e9*.html"
+        ),
+        (("filters", False), ("members", True), ("members_order", "source")): external(
+            "hash:7130f7ac88be*.html"
+        ),
     }
 )
 
@@ -399,63 +407,63 @@ docstring_arguments = snapshot(
         (
             ("docstring_section_style", "table"),
             ("parse_arguments", True),
-            ("show_docstring_examples", False),
-        ): external("hash:433d68533719*.html"),
-        (
-            ("docstring_section_style", "list"),
-            ("parse_arguments", False),
             ("show_docstring_examples", True),
-        ): external("hash:5ef4a55b645c*.html"),
+        ): external("hash:201baee4ccea*.html"),
         (
-            ("docstring_section_style", "spacy"),
+            ("docstring_section_style", "table"),
             ("parse_arguments", False),
             ("show_docstring_examples", True),
-        ): external("hash:5958a350dfbc*.html"),
+        ): external("hash:f5a8a9d05580*.html"),
         (
             ("docstring_section_style", "table"),
-            ("parse_arguments", False),
+            ("parse_arguments", True),
             ("show_docstring_examples", False),
-        ): external("hash:368f6d810e73*.html"),
+        ): external("hash:433d68533719*.html"),
         (
-            ("docstring_section_style", "spacy"),
+            ("docstring_section_style", "table"),
             ("parse_arguments", False),
             ("show_docstring_examples", False),
-        ): external("hash:3307c670266e*.html"),
+        ): external("hash:368f6d810e73*.html"),
         (
-            ("docstring_section_style", "spacy"),
+            ("docstring_section_style", "list"),
             ("parse_arguments", True),
             ("show_docstring_examples", True),
-        ): external("hash:d75158ca9780*.html"),
+        ): external("hash:ba50d6df9b5c*.html"),
         (
-            ("docstring_section_style", "spacy"),
+            ("docstring_section_style", "list"),
+            ("parse_arguments", False),
+            ("show_docstring_examples", True),
+        ): external("hash:5ef4a55b645c*.html"),
+        (
+            ("docstring_section_style", "list"),
             ("parse_arguments", True),
             ("show_docstring_examples", False),
-        ): external("hash:3e7bbbc8686f*.html"),
+        ): external("hash:1271356810fe*.html"),
         (
             ("docstring_section_style", "list"),
             ("parse_arguments", False),
             ("show_docstring_examples", False),
         ): external("hash:ba986803c9e1*.html"),
         (
-            ("docstring_section_style", "table"),
+            ("docstring_section_style", "spacy"),
+            ("parse_arguments", True),
+            ("show_docstring_examples", True),
+        ): external("hash:d75158ca9780*.html"),
+        (
+            ("docstring_section_style", "spacy"),
             ("parse_arguments", False),
             ("show_docstring_examples", True),
-        ): external("hash:f5a8a9d05580*.html"),
+        ): external("hash:5958a350dfbc*.html"),
         (
-            ("docstring_section_style", "list"),
+            ("docstring_section_style", "spacy"),
             ("parse_arguments", True),
             ("show_docstring_examples", False),
-        ): external("hash:1271356810fe*.html"),
-        (
-            ("docstring_section_style", "table"),
-            ("parse_arguments", True),
-            ("show_docstring_examples", True),
-        ): external("hash:201baee4ccea*.html"),
+        ): external("hash:3e7bbbc8686f*.html"),
         (
-            ("docstring_section_style", "list"),
-            ("parse_arguments", True),
-            ("show_docstring_examples", True),
-        ): external("hash:ba50d6df9b5c*.html"),
+            ("docstring_section_style", "spacy"),
+            ("parse_arguments", False),
+            ("show_docstring_examples", False),
+        ): external("hash:3307c670266e*.html"),
     }
 )
 docstring_class = snapshot(
@@ -596,6 +604,7 @@ docstring_style = snapshot(
         (("docstring_style", "google"),): external("hash:f55d6bb2445a*.html"),
         (("docstring_style", "numpy"),): external("hash:bc31b4ef3ece*.html"),
         (("docstring_style", None),): external("hash:c0e27b1c2fd2*.html"),
+        (("docstring_style", "sphinx"),): external("hash:56d44149e879*.html"),
     }
 )
 

mkdocstrings_matlab-1.0.9/test/snapshots/external/56d44149e87990cadcfb34971a0b4a8edf03aed77f3e1dd1bbc127fa4cdcc018.html

@@ -0,0 +1,46 @@
+<!--
+{
+  "docstring_style": "sphinx"
+}
+-->
+
+<div class="doc doc-object doc-function">
+ <h1 class="doc doc-heading" id="forced_docstring">
+  <code class="highlight language-matlab">
+   <span class="n">
+    forced_docstring
+   </span>
+   <span class="p">
+    (
+   </span>
+   <span class="n">
+    inputA
+   </span>
+   <span class="p">
+    ,
+   </span>
+   <span class="w">
+   </span>
+   <span class="n">
+    inputB
+   </span>
+   <span class="p">
+    )
+   </span>
+  </code>
+ </h1>
+ <div class="doc doc-contents first">
+  <p>
+   Docstring for forced_docstring.
+  </p>
+  <p>
+   Arguments:
+  inputA (double): First input parameter
+  inputB (string): Second input parameter
+  </p>
+  <p>
+   Outputs:
+  outputs (struct): A structure containing the results
+  </p>
+ </div>
+</div>

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/test/test_end_to_end.py

@@ -262,7 +262,7 @@ def test_end_to_end_docstring_arguments(
     assert outsource(html, suffix=".html") == snapshots.docstring_arguments[snapshot_key]
 
 
-@pytest.mark.parametrize("docstring_style", ["google", "numpy", None])
+@pytest.mark.parametrize("docstring_style", ["google", "numpy", "sphinx", None])
 def test_end_to_end_docstring_style(
     session_handler: "MatlabHandler",
     docstring_style: str | None,

{mkdocstrings_matlab-1.0.8 → mkdocstrings_matlab-1.0.9}/test/test_handler.py

@@ -230,6 +230,7 @@ def test_matlab_specific_filters(handler: MatlabHandler) -> None:
         "filter_objects",
         "stash_crossref",
         "get_template",
+        "parse_docstring",
         "function_docstring",
         "as_properties_section",
         "as_functions_section",