mkdocstrings-matlab 1.0.7__py3-none-any.whl → 1.0.9__py3-none-any.whl

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["auto", "google", "numpy", "sphinx"] | None,
+        DocstringStyle | None,
         Field(
             group="docstrings",
             description="The docstring style to use: `auto`, `google`, `numpy`, `sphinx`, or `None`.",
         ),
-    ] = "google"
+    ] = "auto"
 
     parse_arguments: Annotated[
         bool,

mkdocstrings_handlers/matlab/handler.py

@@ -132,6 +132,9 @@ class MatlabHandler(BaseHandler):
         template_name = rendering.do_get_template(data)
         template = self.env.get_template(template_name)
 
+        if hasattr(data, "docstring") and data.docstring is not None:
+            data.docstring.parse()
+
         heading_level = options.heading_level
 
         html = template.render(
@@ -166,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_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_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_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_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_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_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_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_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_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_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_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.7.dist-info → mkdocstrings_matlab-1.0.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-matlab
-Version: 1.0.7
+Version: 1.0.9
 Summary: A MATLAB handler for mkdocstrings
 Author-email: Mark Hu <watermarkhu@gmail.com>
 License: MIT
@@ -22,7 +22,7 @@ Classifier: Typing :: Typed
 Requires-Python: <3.14,>=3.10
 Requires-Dist: charset-normalizer~=3.4
 Requires-Dist: griffe~=1.14.0
-Requires-Dist: maxx~=0.4.1
+Requires-Dist: maxx~=0.4.2
 Requires-Dist: mkdocs-autorefs~=1.4
 Requires-Dist: mkdocstrings~=0.29
 Requires-Dist: typing-extensions>=4.0; python_version < '3.11'

{mkdocstrings_matlab-1.0.7.dist-info → mkdocstrings_matlab-1.0.9.dist-info}/RECORD

@@ -1,21 +1,20 @@
 mkdocstrings_handlers/matlab/__init__.py,sha256=zLE8MANvIbg-pEVFc9bGhhIUvqAjnSANBGqek-dm3LM,1721
-mkdocstrings_handlers/matlab/config.py,sha256=yuoB62JOm4vW5uJYd9mqvwIhtfmgSD34CMccc-9aEEc,26724
-mkdocstrings_handlers/matlab/handler.py,sha256=gD0ogRqzOlZAn_iv1E0xFflFj_tUmQcWUeWLPlp1RxI,9803
-mkdocstrings_handlers/matlab/logger.py,sha256=96hRpwOVyvEF0e9f8rvXnNBSBAuHEvM5a6bJNN8hjRo,3298
+mkdocstrings_handlers/matlab/config.py,sha256=zpnTijfd21NTc_gIHSvzkOheUO4NTeNoaTyD62SIcNg,26755
+mkdocstrings_handlers/matlab/handler.py,sha256=QUvqGlFaAvNVsxkjdh8y2xM7f7J-12vU351Ed9bItps,9984
 mkdocstrings_handlers/matlab/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mkdocstrings_handlers/matlab/rendering.py,sha256=yhxpyAcEkCCC6of84ENip5QhEheVNl16E5jNjB53iZs,25726
+mkdocstrings_handlers/matlab/rendering.py,sha256=NhhgO7s6A64_s5U6Zg_wOFWHIzM3Alk6hO-so29zj7g,26227
 mkdocstrings_handlers/matlab/templates/material/attributes.html.jinja,sha256=3Wv9tRkBASmxW3NGdAw9V8mc7G6hc1pDIKmVQztlFJk,818
 mkdocstrings_handlers/matlab/templates/material/backlinks.html.jinja,sha256=FFrvIa-KH-DhT1cpc9HL0ecShR2gUVGs3VT9c1q88z8,467
 mkdocstrings_handlers/matlab/templates/material/children.html.jinja,sha256=gWV77R1BSkVlbQdY_VB9wrGSBY30bcm23skPTfOW1Fs,7517
-mkdocstrings_handlers/matlab/templates/material/class.html.jinja,sha256=vcTCQ9Q5WRLiT6t8mMKopGSQCfmJpnI678kCBxNWmak,9706
+mkdocstrings_handlers/matlab/templates/material/class.html.jinja,sha256=cF4MbUEjlqK0p7LpKozRJyb3ULHVtXDl5VVDO83VSnE,9817
 mkdocstrings_handlers/matlab/templates/material/docstring.html.jinja,sha256=lpdQelVsBwBi0jpO1xCqX-59SmFZ7N269JCNhiae6Pc,2666
 mkdocstrings_handlers/matlab/templates/material/expression.html.jinja,sha256=3srDE2lRULPYAo7PFvy0tMT-2FKo2r6yE8Dvtui1HMI,1921
-mkdocstrings_handlers/matlab/templates/material/folder.html.jinja,sha256=wdr9Mte9cFy_dKbpCnWN2UPreZEZo5EHG23bEHwMd9M,4004
-mkdocstrings_handlers/matlab/templates/material/function.html.jinja,sha256=xJ6E06q9vxHaOxK2cRzP1DvoWqWOCO1NIME7j64dsf8,5659
+mkdocstrings_handlers/matlab/templates/material/folder.html.jinja,sha256=b5fzUclu95-5vVwr6row8Y3GJUJWaxw2e7EU8kPlXM8,4065
+mkdocstrings_handlers/matlab/templates/material/function.html.jinja,sha256=sPiTAknccAhHm0mbJYGcnmjGpQswDCHgzyAZ0DBYaVU,5709
 mkdocstrings_handlers/matlab/templates/material/language.html.jinja,sha256=7gyknTiapqCM8TjUHdXkQgZMmYwcuy6Ze0pkntE7g8s,617
-mkdocstrings_handlers/matlab/templates/material/namespace.html.jinja,sha256=oS8Hiy_BWRRw-Xf-r3Mvi7H3egR7YlKms8bIHk_ocw0,4107
-mkdocstrings_handlers/matlab/templates/material/property.html.jinja,sha256=qS3WyTyhMH5c40TukESjVRirYybGoyhNys4kECegR3I,4579
-mkdocstrings_handlers/matlab/templates/material/script.html.jinja,sha256=doIFI-HiOAqBmSP3RhUsHlE-Djk2xE-MrModxWLM-VQ,4040
+mkdocstrings_handlers/matlab/templates/material/namespace.html.jinja,sha256=AuxgTGzPdXAnjR8Vly19Wh1eHdkR4c_3HVeljHKgk3Y,4168
+mkdocstrings_handlers/matlab/templates/material/property.html.jinja,sha256=yTnaXkGZVsy0rip388yeJJxtta21ImTDY8OjfOej5n8,4640
+mkdocstrings_handlers/matlab/templates/material/script.html.jinja,sha256=7KdPbjSKCVBnSwhmHoYfMT8ub4Wvp1dc2Xg_7HJb2bU,4101
 mkdocstrings_handlers/matlab/templates/material/signature.html.jinja,sha256=2J0XcBlTEGbC-UKCqoMbVmstAKMgszzGyZAIovhDSW0,3946
 mkdocstrings_handlers/matlab/templates/material/style.css,sha256=UgaVpWNzrTNzt_19wH0ryVAhs1GJ5eYK4JKJMHT4h2k,5083
 mkdocstrings_handlers/matlab/templates/material/summary.html.jinja,sha256=NgPQG1FeujVPJc6ePB1lRx7ovMuHqPkkSDVYPXoDWmA,725
@@ -31,11 +30,11 @@ mkdocstrings_handlers/matlab/templates/material/docstring/properties.html.jinja,
 mkdocstrings_handlers/matlab/templates/material/languages/en.html.jinja,sha256=Oen9OTX26S-RfcGYkRQr-FVoIYo1jWpK47UB_47l6S0,1042
 mkdocstrings_handlers/matlab/templates/material/languages/ja.html.jinja,sha256=Urtwz_zgo4ij3SkThxuaCS3x0eLqD0ScejocX-wgWVs,1131
 mkdocstrings_handlers/matlab/templates/material/languages/zh.html.jinja,sha256=qV2S8ikiE1C3TBqwRvKGvAnNtWGqDLn9j_NCOmFi95E,999
-mkdocstrings_handlers/matlab/templates/material/summary/classes.html.jinja,sha256=JuPeZVFHUF398Dw_E-HWoDKlCGFgj52B4W2YJosU4pA,842
-mkdocstrings_handlers/matlab/templates/material/summary/functions.html.jinja,sha256=f19-RvEkHZO4VegiQApq71nAEA27RKwQW3S2NMmKrW4,860
-mkdocstrings_handlers/matlab/templates/material/summary/namespaces.html.jinja,sha256=J0aPYlktc5RY3Gax6GCZDxT5qgFDB5b3eqZZXfZOHxU,845
-mkdocstrings_handlers/matlab/templates/material/summary/properties.html.jinja,sha256=0wQeDtZzfLSZPHJzLG_MVzre1NSyoSHowTwYzk0JX1c,857
-mkdocstrings_matlab-1.0.7.dist-info/METADATA,sha256=2DbOSly9BX0gdF6hluz1x1aAI8WcsyhIWurZL6iDPck,4616
-mkdocstrings_matlab-1.0.7.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mkdocstrings_matlab-1.0.7.dist-info/licenses/LICENSE,sha256=TZQpwBuA3KLH56--XDAY2Qwo9gGdxeTITYhMOylmYhg,743
-mkdocstrings_matlab-1.0.7.dist-info/RECORD,,
+mkdocstrings_handlers/matlab/templates/material/summary/classes.html.jinja,sha256=eALUVZq6MDLZmtaLD_Y9029eQQbFdtHxGKDe44FDWMI,903
+mkdocstrings_handlers/matlab/templates/material/summary/functions.html.jinja,sha256=IhcY4O2HeGYjUjNQ9W9aYiNecCjrTzNVQopgRzxHtz8,921
+mkdocstrings_handlers/matlab/templates/material/summary/namespaces.html.jinja,sha256=fWuFO5a2P-OEky2wvv95XLtB-9PTkymFC9MIQ5XS6FE,906
+mkdocstrings_handlers/matlab/templates/material/summary/properties.html.jinja,sha256=lgVn15U3mg72RjmgvZxCqrRsjx2eEyZ0HM0bt1LxWMM,918
+mkdocstrings_matlab-1.0.9.dist-info/METADATA,sha256=NKl6JG6GBjVwdzalMgDGF1hvfTjIEPHjRJ6y4guQIf4,4616
+mkdocstrings_matlab-1.0.9.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mkdocstrings_matlab-1.0.9.dist-info/licenses/LICENSE,sha256=TZQpwBuA3KLH56--XDAY2Qwo9gGdxeTITYhMOylmYhg,743
+mkdocstrings_matlab-1.0.9.dist-info/RECORD,,

mkdocstrings_handlers/matlab/logger.py

@@ -1,111 +0,0 @@
-# This module contains the logger used throughout Griffe.
-# The logger is actually a wrapper around the standard Python logger.
-# We wrap it so that it is easier for other downstream libraries to patch it.
-# For example, mkdocstrings-python patches the logger to relocate it as a child
-# of `mkdocs.plugins` so that it fits in the MkDocs logging configuration.
-#
-# We use a single, global logger because our public API is exposed in a single module, `griffe`.
-# Extensions however should use their own logger, which is why we provide the `get_logger` function.
-
-from __future__ import annotations
-
-import logging
-from contextlib import contextmanager
-from typing import TYPE_CHECKING, Any, Callable, ClassVar
-
-if TYPE_CHECKING:
-    from collections.abc import Iterator
-
-
-class Logger:
-    _default_logger: Any = logging.getLogger
-    _instances: ClassVar[dict[str, Logger]] = {}
-
-    def __init__(self, name: str) -> None:
-        # Default logger that can be patched by third-party.
-        self._logger = self.__class__._default_logger(name)
-
-    def __getattr__(self, name: str) -> Any:
-        # Forward everything to the logger.
-        return getattr(self._logger, name)
-
-    @contextmanager
-    def disable(self) -> Iterator[None]:
-        """Temporarily disable logging."""
-        old_level = self._logger.level
-        self._logger.setLevel(100)
-        try:
-            yield
-        finally:
-            self._logger.setLevel(old_level)
-
-    @classmethod
-    def _get(cls, name: str = "griffe") -> Logger:
-        if name not in cls._instances:
-            cls._instances[name] = cls(name)
-        return cls._instances[name]
-
-    @classmethod
-    def _patch_loggers(cls, get_logger_func: Callable) -> None:
-        # Patch current instances.
-        for name, instance in cls._instances.items():
-            instance._logger = get_logger_func(name)
-
-        # Future instances will be patched as well.
-        cls._default_logger = get_logger_func
-
-
-logger: Logger = Logger._get()
-"""Our global logger, used throughout the library.
-
-Griffe's output and error messages are logging messages.
-
-Griffe provides the [`patch_loggers`][griffe.patch_loggers]
-function so dependent libraries can patch Griffe loggers as they see fit.
-
-For example, to fit in the MkDocs logging configuration
-and prefix each log message with the module name:
-
-```python
-import logging
-from griffe import patch_loggers
-
-
-class LoggerAdapter(logging.LoggerAdapter):
-    def __init__(self, prefix, logger):
-        super().__init__(logger, {})
-        self.prefix = prefix
-
-    def process(self, msg, kwargs):
-        return f"{self.prefix}: {msg}", kwargs
-
-
-def get_logger(name):
-    logger = logging.getLogger(f"mkdocs.plugins.{name}")
-    return LoggerAdapter(name, logger)
-
-
-patch_loggers(get_logger)
-```
-"""
-
-
-def get_logger(name: str = "griffe") -> Logger:
-    """Create and return a new logger instance.
-
-    Parameters:
-        name: The logger name.
-
-    Returns:
-        The logger.
-    """
-    return Logger._get(name)
-
-
-def patch_loggers(get_logger_func: Callable[[str], Any]) -> None:
-    """Patch Griffe logger and Griffe extensions' loggers.
-
-    Parameters:
-        get_logger_func: A function accepting a name as parameter and returning a logger.
-    """
-    Logger._patch_loggers(get_logger_func)