mkdocstrings-python 1.9.2__py3-none-any.whl → 1.10.1__py3-none-any.whl

mkdocstrings_handlers/python/handler.py

@@ -9,6 +9,7 @@ import re
 import sys
 from collections import ChainMap
 from contextlib import suppress
+from pathlib import Path
 from typing import TYPE_CHECKING, Any, BinaryIO, ClassVar, Iterator, Mapping, Sequence
 
 from griffe.collections import LinesCollection, ModulesCollection
@@ -52,6 +53,8 @@ patch_loggers(get_logger)
 class PythonHandler(BaseHandler):
     """The Python handler class."""
 
+    name = "python"
+    """The handler's name."""
     domain: str = "py"  # to match Sphinx's default domain
     """The cross-documentation domain/language for this handler."""
     enable_inventory: bool = True
@@ -208,21 +211,42 @@ class PythonHandler(BaseHandler):
             **kwargs: Same thing, but with keyword arguments.
         """
         super().__init__(*args, **kwargs)
+
+        # Warn if user overrides base templates.
+        if custom_templates := kwargs.get("custom_templates", ()):
+            config_dir = Path(config_file_path or "./mkdocs.yml").parent
+            for theme_dir in config_dir.joinpath(custom_templates, "python").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",
+                    )
+
         self._config_file_path = config_file_path
         self._load_external_modules = load_external_modules
         paths = paths or []
+
+        # Expand paths with glob patterns.
         glob_base_dir = os.path.dirname(os.path.abspath(config_file_path)) if config_file_path else "."
         with chdir(glob_base_dir):
             resolved_globs = [glob.glob(path) for path in paths]
         paths = [path for glob_list in resolved_globs for path in glob_list]
+
+        # By default, add the directory of the config file to the search paths.
         if not paths and config_file_path:
             paths.append(os.path.dirname(config_file_path))
-        search_paths = [path for path in sys.path if path]  # eliminate empty path
+
+        # Initialize search paths from `sys.path`, eliminating empty paths.
+        search_paths = [path for path in sys.path if path]
+
         for path in reversed(paths):
+            # If it's not absolute, make path relative to the config file path, then make it absolute.
             if not os.path.isabs(path) and config_file_path:
                 path = os.path.abspath(os.path.join(os.path.dirname(config_file_path), path))  # noqa: PLW2901
+            # Don't add duplicates.
             if path not in search_paths:
                 search_paths.insert(0, path)
+
         self._paths = search_paths
         self._modules_collection: ModulesCollection = ModulesCollection()
         self._lines_collection: LinesCollection = LinesCollection()
@@ -321,7 +345,7 @@ class PythonHandler(BaseHandler):
     def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str:  # noqa: D102 (ignore missing docstring)
         final_config = ChainMap(config, self.default_config)  # type: ignore[arg-type]
 
-        template_name = rendering.do_get_template(data)
+        template_name = rendering.do_get_template(self.env, data)
         template = self.env.get_template(template_name)
 
         # Heading level is a "state" variable, that will change at each step
@@ -374,7 +398,13 @@ class PythonHandler(BaseHandler):
             },
         )
 
-    def update_env(self, md: Markdown, config: dict) -> None:  # noqa: D102 (ignore missing docstring)
+    def update_env(self, md: Markdown, config: dict) -> None:
+        """Update the Jinja environment with custom filters and tests.
+
+        Parameters:
+            md: The Markdown instance.
+            config: The configuration dictionary.
+        """
         super().update_env(md, config)
         self.env.trim_blocks = True
         self.env.lstrip_blocks = True

mkdocstrings_handlers/python/rendering.py

@@ -9,20 +9,23 @@ import string
 import sys
 import warnings
 from functools import lru_cache, partial
+from pathlib import Path
 from typing import TYPE_CHECKING, Any, Callable, Match, Pattern, Sequence
 
+from griffe.dataclasses import Alias, Object
 from griffe.docstrings.dataclasses import (
     DocstringSectionAttributes,
     DocstringSectionClasses,
     DocstringSectionFunctions,
     DocstringSectionModules,
 )
-from jinja2 import pass_context
+from jinja2 import TemplateNotFound, pass_context, pass_environment
 from markupsafe import Markup
 from mkdocstrings.loggers import get_logger
 
 if TYPE_CHECKING:
-    from griffe.dataclasses import Alias, Attribute, Class, Function, Module, Object
+    from griffe.dataclasses import Attribute, Class, Function, Module
+    from jinja2 import Environment, Template
     from jinja2.runtime import Context
     from mkdocstrings.handlers.base import CollectorItem
 
@@ -137,7 +140,8 @@ def do_format_signature(
         The same code, formatted.
     """
     env = context.environment
-    template = env.get_template("signature.html")
+    # TODO: Stop using `do_get_template` when `*.html` templates are removed.
+    template = env.get_template(do_get_template(env, "signature"))
     config_annotations = context.parent["config"]["show_signature_annotations"]
     old_stash_ref_filter = env.filters["stash_crossref"]
 
@@ -204,7 +208,8 @@ def do_format_attribute(
         The same code, formatted.
     """
     env = context.environment
-    template = env.get_template("expression.html")
+    # TODO: Stop using `do_get_template` when `*.html` templates are removed.
+    template = env.get_template(do_get_template(env, "expression"))
     annotations = context.parent["config"]["show_signature_annotations"]
     separate_signature = context.parent["config"]["separate_signature"]
     old_stash_ref_filter = env.filters["stash_crossref"]
@@ -448,17 +453,46 @@ def _get_black_formatter() -> Callable[[str, int], str]:
     return formatter
 
 
-def do_get_template(obj: Object) -> str:
+@pass_environment
+def do_get_template(env: Environment, obj: str | Object) -> str | Template:
     """Get the template name used to render an object.
 
     Parameters:
-        obj: A Griffe object.
+        env: The Jinja environment, passed automatically.
+        obj: A Griffe object, or a template name.
 
     Returns:
         A template name.
     """
-    extra_data = getattr(obj, "extra", {}).get("mkdocstrings", {})
-    return extra_data.get("template", "") or f"{obj.kind.value}.html"
+    name = obj
+    if isinstance(obj, (Alias, Object)):
+        extra_data = getattr(obj, "extra", {}).get("mkdocstrings", {})
+        if name := extra_data.get("template", ""):
+            return name
+        name = obj.kind.value
+    try:
+        template = env.get_template(f"{name}.html")
+    except TemplateNotFound:
+        return f"{name}.html.jinja"
+    else:
+        # TODO: Remove once support for Python 3.8 is dropped.
+        if sys.version_info < (3, 9):
+            try:
+                Path(template.filename).relative_to(Path(__file__).parent)  # type: ignore[arg-type]
+            except ValueError:
+                our_template = False
+            else:
+                our_template = True
+        else:
+            our_template = Path(template.filename).is_relative_to(Path(__file__).parent)  # type: ignore[arg-type]
+        if not our_template:
+            # TODO: Switch to a warning log after some time.
+            logger.info(
+                f"DeprecationWarning: Overriding '{name}.html' is deprecated, override '{name}.html.jinja' instead. "
+                "After some time, this message will be logged as a warning, causing strict builds to fail.",
+                once=True,
+            )
+        return f"{name}.html"
 
 
 @pass_context

mkdocstrings_handlers/python/templates/material/_base/attribute.html

@@ -1,80 +1,11 @@
-{{ log.debug("Rendering " + attribute.path) }}
-
-<div class="doc doc-object doc-attribute">
-{% with obj = attribute, html_id = attribute.path %}
-
-  {% if root %}
-    {% set show_full_path = config.show_root_full_path %}
-    {% set root_members = True %}
-  {% elif root_members %}
-    {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
-    {% set root_members = False %}
-  {% else %}
-    {% set show_full_path = config.show_object_full_path %}
-  {% endif %}
-
-  {% set attribute_name = attribute.path if show_full_path else attribute.name %}
-
-  {% if not root or config.show_root_heading %}
-    {% filter heading(
-        heading_level,
-        role="data" if attribute.parent.kind.value == "module" else "attr",
-        id=html_id,
-        class="doc doc-heading",
-        toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + attribute.name,
-    ) %}
-
-      {% block heading scoped %}
-        {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>{% endif %}
-        {% if config.separate_signature %}
-          <span class="doc doc-object-name doc-attribute-name">{{ attribute_name }}</span>
-        {% else %}
-          {%+ filter highlight(language="python", inline=True) %}
-            {{ attribute_name }}{% if attribute.annotation %}: {{ attribute.annotation }}{% endif %}
-            {% if attribute.value %} = {{ attribute.value }}{% endif %}
-          {% endfilter %}
-        {% endif %}
-      {% endblock heading %}
-
-      {% block labels scoped %}
-        {% with labels = attribute.labels %}
-          {% include "labels.html" with context %}
-        {% endwith %}
-      {% endblock labels %}
-
-    {% endfilter %}
-
-    {% block signature scoped %}
-      {% if config.separate_signature %}
-        {% filter format_attribute(attribute, config.line_length, crossrefs=config.signature_crossrefs) %}
-          {{ attribute.name }}
-        {% endfilter %}
-      {% endif %}
-    {% endblock signature %}
-
-  {% else %}
-
-    {% if config.show_root_toc_entry %}
-      {% filter heading(heading_level,
-          role="data" if attribute.parent.kind.value == "module" else "attr",
-          id=html_id,
-          toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + attribute.name,
-          hidden=True,
-      ) %}
-      {% endfilter %}
-    {% endif %}
-    {% set heading_level = heading_level - 1 %}
-  {% endif %}
-
-  <div class="doc doc-contents {% if root %}first{% endif %}">
-    {% block contents scoped %}
-      {% block docstring scoped %}
-        {% with docstring_sections = attribute.docstring.parsed %}
-          {% include "docstring.html" with context %}
-        {% endwith %}
-      {% endblock docstring %}
-    {% endblock contents %}
-  </div>
-
-{% endwith %}
-</div>
+{% extends "_base/attribute.html.jinja" %}
+
+{% block logs scoped %}
+  {{ super() }}
+  {# TODO: Switch to a warning after some time. #}
+  {{ log.info(
+        "DeprecationWarning: Extending '_base/attribute.html' is deprecated, extend '_base/attribute.html.jinja' instead. " ~
+        "After some time, this message will be logged as a warning, causing strict builds to fail.",
+        once=True,
+      ) }}
+{% endblock logs %}

mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja

@@ -0,0 +1,120 @@
+{#- Template for Python attributes.
+
+This template renders a Python attribute (or variable).
+This can be a module attribute or a class attribute.
+
+Context:
+  attribute (griffe.dataclasses.Attribute): The attribute to render.
+  root (bool): Whether this is the root object, injected with `:::` in a Markdown page.
+  heading_level (int): The HTML heading level to use.
+  config (dict): The configuration options.
+-#}
+
+{% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
+  {{ log.debug("Rendering " + attribute.path) }}
+{% endblock logs %}
+
+<div class="doc doc-object doc-attribute">
+  {% with obj = attribute, html_id = attribute.path %}
+
+    {% if root %}
+      {% set show_full_path = config.show_root_full_path %}
+      {% set root_members = True %}
+    {% elif root_members %}
+      {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+      {% set root_members = False %}
+    {% else %}
+      {% set show_full_path = config.show_object_full_path %}
+    {% endif %}
+
+    {% set attribute_name = attribute.path if show_full_path else attribute.name %}
+
+    {% if not root or config.show_root_heading %}
+      {% filter heading(
+          heading_level,
+          role="data" if attribute.parent.kind.value == "module" else "attr",
+          id=html_id,
+          class="doc doc-heading",
+          toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + attribute.name,
+        ) %}
+
+        {% block heading scoped %}
+          {#- Heading block.
+          
+          This block renders the heading for the attribute.
+          -#}
+          {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>{% endif %}
+          {% if config.separate_signature %}
+            <span class="doc doc-object-name doc-attribute-name">{{ attribute_name }}</span>
+          {% else %}
+            {%+ filter highlight(language="python", inline=True) %}
+              {{ attribute_name }}{% if attribute.annotation %}: {{ attribute.annotation }}{% endif %}
+              {% if attribute.value %} = {{ attribute.value }}{% endif %}
+            {% endfilter %}
+          {% endif %}
+        {% endblock heading %}
+
+        {% block labels scoped %}
+          {#- Labels block.
+          
+          This block renders the labels for the attribute.
+          -#}
+          {% with labels = attribute.labels %}
+            {% include "labels"|get_template with context %}
+          {% endwith %}
+        {% endblock labels %}
+
+      {% endfilter %}
+
+      {% block signature scoped %}
+        {#- Signature block.
+        
+        This block renders the signature for the attribute.
+        -#}
+        {% if config.separate_signature %}
+          {% filter format_attribute(attribute, config.line_length, crossrefs=config.signature_crossrefs) %}
+            {{ attribute.name }}
+          {% endfilter %}
+        {% endif %}
+      {% endblock signature %}
+
+    {% else %}
+
+      {% if config.show_root_toc_entry %}
+        {% filter heading(heading_level,
+            role="data" if attribute.parent.kind.value == "module" else "attr",
+            id=html_id,
+            toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + attribute.name,
+            hidden=True,
+          ) %}
+        {% endfilter %}
+      {% endif %}
+      {% set heading_level = heading_level - 1 %}
+    {% endif %}
+
+    <div class="doc doc-contents {% if root %}first{% endif %}">
+      {% block contents scoped %}
+        {#- Contents block.
+        
+        This block renders the contents of the attribute.
+        It contains other blocks that users can override.
+        Overriding the contents block allows to rearrange the order of the blocks.
+        -#}
+        {% block docstring scoped %}
+          {#- Docstring block.
+          
+          This block renders the docstring for the attribute.
+          -#}
+          {% with docstring_sections = attribute.docstring.parsed %}
+            {% include "docstring"|get_template with context %}
+          {% endwith %}
+        {% endblock docstring %}
+      {% endblock contents %}
+    </div>
+
+  {% endwith %}
+</div>

mkdocstrings_handlers/python/templates/material/_base/children.html

@@ -1,154 +1,11 @@
-{% if obj.members %}
-  {{ log.debug("Rendering children of " + obj.path) }}
-
-  <div class="doc doc-children">
-
-    {% if root_members %}
-      {% set members_list = config.members %}
-    {% else %}
-      {% set members_list = none %}
-    {% endif %}
-
-    {% if config.group_by_category %}
-
-      {% with %}
-
-        {% if config.show_category_heading %}
-          {% set extra_level = 1 %}
-        {% else %}
-          {% set extra_level = 0 %}
-        {% endif %}
-
-        {% with attributes = obj.attributes|filter_objects(
-          filters=config.filters,
-          members_list=members_list,
-          inherited_members=config.inherited_members,
-          keep_no_docstrings=config.show_if_no_docstring,
-        ) %}
-          {% if attributes %}
-            {% if config.show_category_heading %}
-              {% filter heading(heading_level, id=html_id ~ "-attributes") %}Attributes{% endfilter %}
-            {% endif %}
-            {% with heading_level = heading_level + extra_level %}
-              {% for attribute in attributes|order_members(config.members_order, members_list) %}
-                {% if members_list is not none or attribute.is_public(check_name=False) %}
-                  {% include attribute|get_template with context %}
-                {% endif %}
-              {% endfor %}
-            {% endwith %}
-          {% endif %}
-        {% endwith %}
-
-        {% with classes = obj.classes|filter_objects(
-          filters=config.filters,
-          members_list=members_list,
-          inherited_members=config.inherited_members,
-          keep_no_docstrings=config.show_if_no_docstring,
-        ) %}
-          {% if classes %}
-            {% if config.show_category_heading %}
-              {% filter heading(heading_level, id=html_id ~ "-classes") %}Classes{% endfilter %}
-            {% endif %}
-            {% with heading_level = heading_level + extra_level %}
-              {% for class in classes|order_members(config.members_order, members_list) %}
-                {% if members_list is not none or class.is_public(check_name=False) %}
-                  {% include class|get_template with context %}
-                {% endif %}
-              {% endfor %}
-            {% endwith %}
-          {% endif %}
-        {% endwith %}
-
-        {% with functions = obj.functions|filter_objects(
-          filters=config.filters,
-          members_list=members_list,
-          inherited_members=config.inherited_members,
-          keep_no_docstrings=config.show_if_no_docstring,
-        ) %}
-          {% if functions %}
-            {% if config.show_category_heading %}
-              {% filter heading(heading_level, id=html_id ~ "-functions") %}Functions{% endfilter %}
-            {% endif %}
-            {% with heading_level = heading_level + extra_level %}
-              {% for function in functions|order_members(config.members_order, members_list) %}
-                {% if not (obj.kind.value == "class" and function.name == "__init__" and config.merge_init_into_class) %}
-                  {% if members_list is not none or function.is_public(check_name=False) %}
-                    {% include function|get_template with context %}
-                  {% endif %}
-                {% endif %}
-              {% endfor %}
-            {% endwith %}
-          {% endif %}
-        {% endwith %}
-
-        {% if config.show_submodules %}
-          {% with modules = obj.modules|filter_objects(
-            filters=config.filters,
-            members_list=members_list,
-            inherited_members=config.inherited_members,
-            keep_no_docstrings=config.show_if_no_docstring,
-          ) %}
-            {% if modules %}
-              {% if config.show_category_heading %}
-                {% filter heading(heading_level, id=html_id ~ "-modules") %}Modules{% endfilter %}
-              {% endif %}
-              {% with heading_level = heading_level + extra_level %}
-                {% for module in modules|order_members(config.members_order.alphabetical, members_list) %}
-                  {% if members_list is not none or module.is_public(check_name=False) %}
-                    {% include module|get_template with context %}
-                  {% endif %}
-                {% endfor %}
-              {% endwith %}
-            {% endif %}
-          {% endwith %}
-        {% endif %}
-
-      {% endwith %}
-
-    {% else %}
-
-      {% for child in obj.all_members
-        |filter_objects(
-          filters=config.filters,
-          members_list=members_list,
-          inherited_members=config.inherited_members,
-          keep_no_docstrings=config.show_if_no_docstring,
-        )
-        |order_members(config.members_order, members_list)
-      %}
-
-        {% if not (obj.is_class and child.name == "__init__" and config.merge_init_into_class) %}
-
-          {% if members_list is not none or child.is_public(check_name=False) %}
-            {% if child.is_attribute %}
-              {% with attribute = child %}
-                {% include attribute|get_template with context %}
-              {% endwith %}
-
-            {% elif child.is_class %}
-              {% with class = child %}
-                {% include class|get_template with context %}
-              {% endwith %}
-
-            {% elif child.is_function %}
-              {% with function = child %}
-                {% include function|get_template with context %}
-              {% endwith %}
-
-            {% elif child.is_module and config.show_submodules %}
-              {% with module = child %}
-                {% include module|get_template with context %}
-              {% endwith %}
-
-            {% endif %}
-          {% endif %}
-
-        {% endif %}
-
-      {% endfor %}
-
-    {% endif %}
-
-  </div>
-
-{% endif %}
+{% extends "_base/children.html.jinja" %}
+
+{% block logs scoped %}
+  {{ super() }}
+  {# TODO: Switch to a warning after some time. #}
+  {{ log.info(
+        "DeprecationWarning: Extending '_base/children.html' is deprecated, extend '_base/children.html.jinja' instead. " ~
+        "After some time, this message will be logged as a warning, causing strict builds to fail.",
+        once=True,
+      ) }}
+{% endblock logs %}