mkdocstrings-matlab 0.9.7__py3-none-any.whl → 1.0.0__py3-none-any.whl

mkdocstrings_handlers/matlab/handler.py

@@ -1,347 +1,189 @@
 """The mkdocstrings handler for processing MATLAB code documentation."""
 
-import re
-from collections import ChainMap
+from __future__ import annotations
+
+from contextlib import suppress
+from dataclasses import asdict
 from pathlib import Path
-from pprint import pprint
-from typing import Any, ClassVar, Mapping
+from typing import TYPE_CHECKING, Any, ClassVar
 
-from jinja2.loaders import FileSystemLoader
-from markdown import Markdown
+from griffe import AliasResolutionError, Parser
+from maxx.collection import LinesCollection, PathsCollection
 from mkdocs.exceptions import PluginError
-from mkdocstrings.handlers.base import BaseHandler, CollectionError, CollectorItem
+from mkdocstrings import (
+    BaseHandler,
+    CollectionError,
+    CollectorItem,
+    HandlerOptions,
+    get_logger,
+)
+
+from mkdocstrings_handlers.matlab import rendering
+from mkdocstrings_handlers.matlab.config import MatlabConfig, MatlabOptions
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, MutableMapping
 
-from mkdocstrings_handlers.matlab.collect import LinesCollection, PathCollection
-from mkdocstrings_handlers.python import rendering
+    from mkdocs.config.defaults import MkDocsConfig
+
+
+_logger = get_logger(__name__)
 
 
 class MatlabHandler(BaseHandler):
     """The `MatlabHandler` class is a handler for processing Matlab code documentation."""
 
-    name: str = "matlab"
-    """The handler's name."""
-    domain: str = "mat"  # to match Sphinx's default domain
+    name: ClassVar[str] = "matlab"
+    """The MATLAB handler class."""
+
+    domain: ClassVar[str] = "mat"  # to match Sphinx's default domain
     """The cross-documentation domain/language for this handler."""
-    enable_inventory: bool = True
+
+    enable_inventory: ClassVar[bool] = True
     """Whether this handler is interested in enabling the creation of the `objects.inv` Sphinx inventory file."""
-    fallback_theme = "material"
+
+    fallback_theme: ClassVar[str] = "material"
     """The fallback theme."""
-    fallback_config: ClassVar[dict] = {
-        "fallback": True,
-    }
-    """The configuration used to collect item during autorefs fallback."""
-    default_config: ClassVar[dict] = {
-        # General options
-        "show_bases": True,
-        "show_inheritance_diagram": False,
-        "show_source": True,
-        # Heading options
-        "heading_level": 2,
-        "parameter_headings": False,
-        "show_root_heading": False,
-        "show_root_toc_entry": True,
-        "show_root_full_path": True,
-        "show_root_members_full_path": False,
-        "show_object_full_path": False,
-        "show_category_heading": False,
-        "show_symbol_type_heading": False,
-        "show_symbol_type_toc": False,
-        # Member options
-        "members": None,
-        "hidden_members": False,
-        "private_members": False,
-        "inherited_members": False,
-        "members_order": rendering.Order.alphabetical.value,
-        "filters": ["!^delete$|^disp$"],
-        "group_by_category": True,
-        "show_subnamespaces": False,
-        "summary": False,
-        "show_labels": True,
-        # Docstring options
-        "docstring_style": "google",
-        "docstring_options": {},
-        "docstring_section_style": "table",
-        "parse_arguments": False,
-        "merge_constructor_into_class": False,
-        "merge_constructor_ignore_summary": False,
-        "show_if_no_docstring": False,
-        "show_docstring_propeties": True,
-        "show_docstring_functions": True,
-        "show_docstring_classes": True,
-        "show_docstring_namespaces": True,
-        "show_docstring_description": True,
-        "show_docstring_examples": True,
-        "show_docstring_input_arguments": True,
-        "show_docstring_name_value_arguments": True,
-        "show_docstring_output_arguments": True,
-        # Signature options
-        "show_signature": True,
-        "show_signature_annotations": False,
-        "separate_signature": False,
-        "signature_crossrefs": False,
-    }
-    """Default handler configuration.
-
-    Attributes: General options:
-        show_bases (bool): Show the base classes of a class. Default: `True`.
-        show_inheritance_diagram (bool): Show the inheritance diagram of a class using Mermaid. Default: `False`.
-        show_source (bool): Show the source code of this object. Default: `True`.
-
-
-    Attributes: Headings options:
-        heading_level (int): The initial heading level to use. Default: `2`.
-        parameter_headings (bool): Whether to render headings for parameters (therefore showing parameters in the ToC). Default: `False`.
-        show_root_heading (bool): Show the heading of the object at the root of the documentation tree
-            (i.e. the object referenced by the identifier after `:::`). Default: `False`.
-        show_root_toc_entry (bool): If the root heading is not shown, at least add a ToC entry for it. Default: `True`.
-        show_root_full_path (bool): Show the full path for the root object heading. Default: `True`.
-        show_root_members_full_path (bool): Show the full path of the root members. Default: `False`.
-        show_object_full_path (bool): Show the full path of every object. Default: `False`.
-        show_category_heading (bool): When grouped by categories, show a heading for each category. Default: `False`.
-        show_symbol_type_heading (bool): Show the symbol type in headings (e.g. mod, class, meth, func and attr). Default: `False`.
-        show_symbol_type_toc (bool): Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr). Default: `False`.
-
-    Attributes: Members options:
-        members (list[str] | bool | None): A boolean, or an explicit list of members to render.
-            If true, select all members without further filtering.
-            If false or empty list, do not render members.
-            If none, select all members and apply further filtering with filters and docstrings. Default: `None`.
-        hidden_members (list[str] | bool | None): A boolean, or an explicit list of hidden members to render. 
-            If true, select all inherited members, which can then be filtered with `members`.
-            If false or empty list, do not select any hidden member. Default: `False`.
-        private_members (list[str] | bool | None): A boolean, or an explicit list of private members to render. 
-            If true, select all inherited members, which can then be filtered with `members`.
-            If false or empty list,  do not select any private member.  Default: `False`.
-        inherited_members (list[str] | bool | None): A boolean, or an explicit list of inherited members to render.
-            If true, select all inherited members, which can then be filtered with `members`.
-            If false or empty list, do not select any inherited member. Default: `False`.
-        members_order (str): The members ordering to use. Options: `alphabetical` - order by the members names,
-            `source` - order members as they appear in the source file. Default: `"alphabetical"`.
-        filters (list[str] | None): A list of filters applied to filter objects based on their name.
-            A filter starting with `!` will exclude matching objects instead of including them.
-            The `members` option takes precedence over `filters` (filters will still be applied recursively
-            to lower members in the hierarchy). Default: `["!^delete$|^disp$"]`.
-        group_by_category (bool): Group the object's children by categories: properties, classes, functions, and namespaces. Default: `True`.
-        show_subnamespaces (bool): When rendering a namespace, show its subnamespaces recursively. Default: `False`.
-        summary (bool | dict[str, bool]): Whether to render summaries of namespaces, classes, functions (methods) and properties. Default: `False`.
-        show_labels (bool): Whether to show labels of the members. Default: `True`.
-
-    Attributes: Docstrings options:
-        docstring_style (str): The docstring style to use: `google`, `numpy`, `sphinx`, or `None`. Default: `"google"`.
-        docstring_options (dict): The options for the docstring parser. See [docstring parsers](https://mkdocstrings.github.io/griffe/reference/docstrings/) and their options in Griffe docs.
-        docstring_section_style (str): The style used to render docstring sections. Options: `table`, `list`, `spacy`. Default: `"table"`.
-        parse_arguments (bool): Whether to load inputs and output parameters based on argument validation blocks. Default: `True`.
-        merge_constructor_into_class (bool): Whether to merge the constructor method into the class' signature and docstring. Default: `False`.
-        merge_constructor_ignore_summary (bool): Whether to ignore the constructor summary when merging it into the class. Default: `False`.
-        show_if_no_docstring (bool): Show the object heading even if it has no docstring or children with docstrings. Default: `False`.
-        show_docstring_properties (bool): Whether to display the "Properties" section in the object's docstring. Default: `True`.
-        show_docstring_functions (bool): Whether to display the "Functions" or "Methods" sections in the object's docstring. Default: `True`.
-        show_docstring_classes (bool): Whether to display the "Classes" section in the object's docstring. Default: `True`.
-        show_docstring_namespaces (bool): Whether to display the "Namespaces" section in the object's docstring. Default: `True`.
-        show_docstring_description (bool): Whether to display the textual block (including admonitions) in the object's docstring. Default: `True`.
-        show_docstring_examples (bool): Whether to display the "Examples" section in the object's docstring. Default: `True`.
-        show_docstring_input_arguments (bool): Whether to display the "Input arguments" section in the object's docstring. Default: `True`.
-        show_docstring_name_value_arguments (bool): Whether to display the "Name-value pairs" section in the object's docstring. Default: `True`.
-        show_docstring_output_arguments (bool): Whether to display the "Output arguments" section in the object's docstring. Default: `True`.
-
-    Attributes: Signatures/annotations options:
-        show_signature (bool): Show methods and functions signatures. Default: `True`.
-        show_signature_annotations (bool): Show the type annotations in methods and functions signatures. Default: `False`.
-        separate_signature (bool): Whether to put the whole signature in a code block below the heading.
-        signature_crossrefs (bool): Whether to render cross-references for type annotations in signatures. Default: `False`.
-    """
 
     def __init__(
         self,
-        handler: str,
-        theme: str,
-        custom_templates: str | None = None,
-        config_file_path: str | None = None,
-        paths: list[str] | None = None,
-        paths_recursive: bool = False,
-        locale: str = "en",
+        config: MatlabConfig,
+        base_dir: Path,
         **kwargs: Any,
     ) -> None:
         """
         Initialize the handler with the given configuration.
 
         Args:
-            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.
-            locale (str, optional): Locale setting. Defaults to "en".
-            **kwargs (Any): Arbitrary keyword arguments.
+            config: The handler configuration.
+            base_dir: The base directory of the project.
+            **kwargs: Arguments passed to the parent constructor.
 
         Returns:
             None
         """
-
-        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
+        super().__init__(**kwargs)
+
+        self.config = config
+        self.base_dir = base_dir
+        self.global_options = config.options
+
+        # Warn if user overrides base templates.
+        if self.custom_templates:
+            for theme_dir in base_dir.joinpath(self.custom_templates, "matlab").iterdir():
+                if theme_dir.joinpath("_base").is_dir():
+                    _logger.warning(
+                        f"Overriding base template '{theme_dir.name}/_base/<template>.html.jinja' is not supported, "
+                        f"override '{theme_dir.name}/<template>.html.jinja' instead",
+                    )
+
+        if config.paths:
             full_paths = []
+            for path in config.paths:
+                if "*" in path:
+                    full_paths.extend([d for d in base_dir.glob(path) if d.is_dir()])
+                else:
+                    full_paths.append((base_dir / path).resolve())
         else:
-            config_path = Path(config_file_path).resolve().parent
-            full_paths = [(config_path / path).resolve() for path in paths]
+            full_paths = []
 
-        if pathIds := [str(path) for path in full_paths if not path.is_dir()]:
+        if path_ids := [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)
+                "The following paths do not exist or are not directories: " + ", ".join(path_ids)
             )
 
-        self.paths: PathCollection = PathCollection(
-            full_paths, recursive=paths_recursive, config_path=config_path
+        self._paths = full_paths
+        self._paths_collection: PathsCollection = PathsCollection(
+            full_paths, recursive=config.paths_recursive, working_directory=base_dir
         )
-        self.lines: LinesCollection = self.paths.lines_collection
-        self._locale: str = locale
+        self._lines_collection: LinesCollection = self._paths_collection.lines_collection
+
+    def get_options(self, local_options: Mapping[str, Any]) -> HandlerOptions:
+        """Get combined default, global and local options.
+
+        Arguments:
+            local_options: The local options.
 
-    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")
+        Returns:
+            The combined options.
+        """
 
-    def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str:
+        extra = {
+            **self.global_options.get("extra", {}),
+            **local_options.get("extra", {}),
+        }
+        options = {**self.global_options, **local_options, "extra": extra}
+        try:
+            return MatlabOptions.from_data(**options)
+        except Exception as error:
+            raise PluginError(f"Invalid options: {error}") from error
+
+    def render(self, data: CollectorItem, options: MatlabOptions) -> str:
         """Render a template using provided data and configuration options.
 
         Arguments:
             data: The collected data to render.
-            config: The handler's configuration options.
+            options: The handler's configuration options.
 
         Returns:
             The rendered template as HTML.
         """
-        final_config = ChainMap(config, self.default_config)  # type: ignore[arg-type]
 
-        template_name = rendering.do_get_template(self.env, data)
+        template_name = rendering.do_get_template(data)
         template = self.env.get_template(template_name)
 
-        heading_level = final_config["heading_level"]
-
-        try:
-            final_config["members_order"] = rendering.Order(
-                final_config["members_order"]
-            )
-        except ValueError as error:
-            choices = "', '".join(item.value for item in rendering.Order)
-            raise PluginError(
-                f"Unknown members_order '{final_config['members_order']}', choose between '{choices}'.",
-            ) from error
-
-        if final_config["filters"]:
-            final_config["filters"] = [
-                (re.compile(filtr.lstrip("!")), filtr.startswith("!"))
-                for filtr in final_config["filters"]
-            ]
-
-        summary = final_config["summary"]
-        if summary is True:
-            final_config["summary"] = {
-                "attributes": True,
-                "functions": True,
-                "classes": True,
-                "modules": True,
-            }
-        elif summary is False:
-            final_config["summary"] = {
-                "attributes": False,
-                "functions": False,
-                "classes": False,
-                "modules": False,
-            }
-        else:
-            final_config["summary"] = {
-                "attributes": summary.get(
-                    "properties", False
-                ),  # Map properties (MATLAB) to attributes (Python)
-                "functions": summary.get("functions", False),
-                "classes": summary.get("classes", False),
-                "modules": summary.get(
-                    "namespaces", False
-                ),  # Map namespaces (MATLAB) to modules (Python)
-            }
-
-        # Map docstring options
-        final_config["show_docstring_attributes"] = config.get(
-            "show_docstring_properties", True
-        )
-        final_config["show_docstring_modules"] = config.get(
-            "show_docstring_namespaces", True
-        )
-        final_config["show_docstring_parameters"] = config.get(
-            "show_docstring_input_arguments", True
-        )
-        final_config["show_docstring_other_parameters"] = config.get(
-            "show_docstring_name_value_arguments", True
-        )
-        final_config["show_docstring_returns"] = config.get(
-            "show_docstring_output_arguments", True
-        )
+        heading_level = options.heading_level
 
-        # These settings must be present to avoid errors
-        for setting in [
-            "merge_init_into_class",
-            "show_docstring_raises",
-            "show_docstring_receives",
-            "show_docstring_yields",
-            "show_docstring_warns",
-        ]:
-            final_config[setting] = False
-        final_config["line_length"] = 88
-
-        return template.render(
+        html = template.render(
             **{
-                "config": final_config,
+                "config": options,
                 data.kind.value: data,
                 "heading_level": heading_level,
                 "root": True,
-                "locale": self._locale,
+                "locale": self.config.locale,
             },
         )
 
-    def update_env(self, md: Markdown, config: dict) -> None:
+        if self.env.filters["stash_crossref"].stash:
+            pass
+
+        return html
+
+    def update_env(self, config: Any) -> None:  # noqa: ARG002
         """Update the Jinja environment with custom filters and tests.
 
         Parameters:
-            md: The Markdown instance.
-            config: The configuration dictionary.
+            config: The SSG configuration.
         """
-        super().update_env(md, config)
         self.env.trim_blocks = True
         self.env.lstrip_blocks = True
         self.env.keep_trailing_newline = False
-        self.env.filters["split_path"] = rendering.do_split_path
-        self.env.filters["crossref"] = rendering.do_crossref
-        self.env.filters["multi_crossref"] = rendering.do_multi_crossref
         self.env.filters["order_members"] = rendering.do_order_members
-        self.env.filters["format_code"] = rendering.do_format_code
         self.env.filters["format_signature"] = rendering.do_format_signature
-        self.env.filters["format_attribute"] = rendering.do_format_attribute
+        self.env.filters["format_property"] = rendering.do_format_property
+        self.env.filters["format_arguments"] = rendering.do_format_arguments
         self.env.filters["filter_objects"] = rendering.do_filter_objects
         self.env.filters["stash_crossref"] = rendering.do_stash_crossref
         self.env.filters["get_template"] = rendering.do_get_template
-        self.env.filters["as_attributes_section"] = rendering.do_as_attributes_section
+        self.env.filters["function_docstring"] = rendering.do_function_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
-        self.env.filters["as_modules_section"] = rendering.do_as_modules_section
+        self.env.filters["as_namespaces_section"] = rendering.do_as_namespaces_section
+        self.env.filters["as_inheritance_diagram_section"] = (
+            rendering.do_as_inheritance_diagram_section
+        )
         self.env.globals["AutorefsHook"] = rendering.AutorefsHook
         self.env.tests["existing_template"] = (
             lambda template_name: template_name in self.env.list_templates()
         )
+        # The following is required since in MATLAB there is a concept called namespace
+        # This is used as a variable in Jinja templates and would overwrite the namespace macro
+        # Thus we create an alias for this.
+        self.env.globals["jinja_namespace"] = self.env.globals["namespace"]
+        self.env.globals["paths_collection"] = self._paths_collection
 
-    def collect(self, identifier: str, config: Mapping[str, Any]) -> CollectorItem:
+    def collect(self, identifier: str, options: MatlabOptions) -> CollectorItem:
         """Collect data given an identifier and user configuration.
 
         In the implementation, you typically call a subprocess that returns JSON, and load that JSON again into
@@ -349,7 +191,7 @@ class MatlabHandler(BaseHandler):
 
         Arguments:
             identifier: An identifier for which to collect data.
-            config: The handler's configuration options.
+            options: The handler's configuration options.
 
         Returns:
             CollectorItem
@@ -357,51 +199,68 @@ class MatlabHandler(BaseHandler):
         if identifier == "":
             raise CollectionError("Empty identifier")
 
-        final_config = ChainMap(config, self.default_config)  # type: ignore[arg-type]
+        if options == {}:
+            options = self.get_options({})
+
         try:
-            model = self.paths.resolve(identifier, config=final_config)
+            if "/" in identifier:
+                # If the identifier contains a slash, it is a path to a file.
+                # We use the lines collection to get the model.
+                path = (self.base_dir / identifier).resolve()
+                if path in self._paths_collection._folders:
+                    # If the path is a folder, we return the folder model.
+                    model = self._paths_collection._folders[path]
+                else:
+                    raise CollectionError(
+                        f"Path '{identifier}' is not a valid path in the collection"
+                    )
+            else:
+                model = self._paths_collection.get_member(identifier)
         except SyntaxError as ex:
             msg = str(ex)
             if ex.text:
-                msg += ":\n" + ex.text
+                msg += ":\n" + str(ex.text)
             raise CollectionError(msg) from ex
-        except Exception as ex:
+        except KeyError as ex:
+            raise CollectionError(str(ex)) from ex
+        except AliasResolutionError as ex:
             raise CollectionError(str(ex)) from ex
+
         if model is None:
             raise CollectionError(f"Identifier '{identifier}' not found")
+
+        parser_name = options.docstring_style
+        parser = parser_name and Parser(parser_name)
+        parser_options = options.docstring_options and asdict(
+            options.docstring_options  # ty: ignore[invalid-argument-type]
+        )
+
+        with suppress(AliasResolutionError):
+            if model.docstring is not None:
+                model.docstring.parser = parser
+                model.docstring.parser_options = parser_options or {}
+
         return model
 
 
 def get_handler(
-    *,
-    theme: str,
-    custom_templates: str | None = None,
-    config_file_path: str | None = None,
-    **config: Any,
+    handler_config: MutableMapping[str, Any],
+    tool_config: MkDocsConfig,
+    **kwargs: Any,
 ) -> MatlabHandler:
     """
     Create and return a MatlabHandler object with the specified configuration.
 
     Parameters:
-        theme (str): The theme to be used by the handler.
-        custom_templates (str | None, optional): Path to custom templates. Defaults to None.
-        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.
-        **config (Any): Additional configuration options.
+         handler_config: The handler configuration.
+        tool_config: The tool (SSG) configuration.
 
     Returns:
         MatlabHandler: An instance of MatlabHandler configured with the provided parameters.
     """
+    base_dir = Path(tool_config.config_file_path or "./mkdocs.yml").parent
     return MatlabHandler(
-        handler="matlab",
-        theme=theme,
-        custom_templates=custom_templates,
-        config_file_path=config_file_path,
-        **config['handler_config']
+        config=MatlabConfig.from_data(**handler_config),
+        base_dir=base_dir,
+        **kwargs,
     )
-
-
-if __name__ == "__main__":
-    handler = get_handler(theme="material")
-    pprint(handler.collect("matlab_startup", {}).docstring.parse("google"))

mkdocstrings_handlers/matlab/logger.py

@@ -0,0 +1,111 @@
+# 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)