.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 @@ def collect(self, identifier: str, config: Mapping[str, Any]) -> CollectorItem:
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 @@ def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str: # noqa
},
)
- 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
diff --git a/src/mkdocstrings_handlers/python/rendering.py b/src/mkdocstrings_handlers/python/rendering.py
index 878b74aa..479597c2 100644
--- a/src/mkdocstrings_handlers/python/rendering.py
+++ b/src/mkdocstrings_handlers/python/rendering.py
@@ -9,20 +9,23 @@
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 formatter(code: str, line_length: 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
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html
index 3f1d887e..7effc590 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html
@@ -1,80 +1,11 @@
-{{ log.debug("Rendering " + attribute.path) }}
-
-
-{% 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=('
'|safe if config.show_symbol_type_toc else '') + attribute.name,
- ) %}
-
- {% block heading scoped %}
- {% if config.show_symbol_type_heading %}
{% endif %}
- {% if config.separate_signature %}
-
{{ attribute_name }}
- {% 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=('
'|safe if config.show_symbol_type_toc else '') + attribute.name,
- hidden=True,
- ) %}
- {% endfilter %}
- {% endif %}
- {% set heading_level = heading_level - 1 %}
- {% endif %}
-
-
- {% block contents scoped %}
- {% block docstring scoped %}
- {% with docstring_sections = attribute.docstring.parsed %}
- {% include "docstring.html" with context %}
- {% endwith %}
- {% endblock docstring %}
- {% endblock contents %}
-
-
-{% endwith %}
-
+ {% 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=('
'|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 %}
{% endif %}
+ {% if config.separate_signature %}
+
{{ attribute_name }}
+ {% 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=('
'|safe if config.show_symbol_type_toc else '') + attribute.name,
+ hidden=True,
+ ) %}
+ {% endfilter %}
+ {% endif %}
+ {% set heading_level = heading_level - 1 %}
+ {% 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 %}
+
+
+ {% endwith %}
+
-
- {% 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 %}
-
-
-
-{% 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 %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja
new file mode 100644
index 00000000..b0ec4007
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja
@@ -0,0 +1,172 @@
+{#- Template for members (children) of an object.
+
+This template iterates on members of a given object and renders them.
+It can group members by category (attributes, classes, functions, modules) or render them in a flat list.
+
+Context:
+ obj (griffe.dataclasses.Object): The object to render.
+ config (dict): The configuration options.
+ root_members (bool): Whether the object is the root object.
+ heading_level (int): The HTML heading level to use.
+-#}
+
+{% if obj.members %}
+ {% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering children of " + obj.path) }}
+ {% endblock logs %}
+
+
+
+ {% 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 %}
+
+
+
+{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html b/src/mkdocstrings_handlers/python/templates/material/_base/class.html
index fb7ca764..ac3e421e 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html
@@ -1,142 +1,11 @@
-{{ log.debug("Rendering " + class.path) }}
-
-
-{% with obj = class, html_id = class.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 class_name = class.path if show_full_path else class.name %}
-
- {% if not root or config.show_root_heading %}
- {% filter heading(
- heading_level,
- role="class",
- id=html_id,
- class="doc doc-heading",
- toc_label=('
'|safe if config.show_symbol_type_toc else '') + class.name,
- ) %}
-
- {% block heading scoped %}
- {% if config.show_symbol_type_heading %}
{% endif %}
- {% if config.separate_signature %}
-
{{ class_name }}
- {% elif config.merge_init_into_class and "__init__" in class.all_members %}
- {% with function = class.all_members["__init__"] %}
- {%+ filter highlight(language="python", inline=True) %}
- {{ class_name }}{% include "signature.html" with context %}
- {% endfilter %}
- {% endwith %}
- {% else %}
-
{{ class_name }}
- {% endif %}
- {% endblock heading %}
-
- {% block labels scoped %}
- {% with labels = class.labels %}
- {% include "labels.html" with context %}
- {% endwith %}
- {% endblock labels %}
-
- {% endfilter %}
-
- {% block signature scoped %}
- {% if config.separate_signature and config.merge_init_into_class %}
- {% if "__init__" in class.all_members %}
- {% with function = class.all_members["__init__"] %}
- {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %}
- {{ class.name }}
- {% endfilter %}
- {% endwith %}
- {% endif %}
- {% endif %}
- {% endblock signature %}
-
- {% else %}
- {% if config.show_root_toc_entry %}
- {% filter heading(heading_level,
- role="class",
- id=html_id,
- toc_label=('
'|safe if config.show_symbol_type_toc else '') + class.name,
- hidden=True,
- ) %}
- {% endfilter %}
- {% endif %}
- {% set heading_level = heading_level - 1 %}
- {% endif %}
-
-
- {% block contents scoped %}
- {% block bases scoped %}
- {% if config.show_bases and class.bases %}
-
- Bases: {% for expression in class.bases -%}
- {% include "expression.html" with context %}{% if not loop.last %}, {% endif %}
- {% endfor -%}
-
- {% endif %}
- {% endblock bases %}
-
- {% block docstring scoped %}
- {% with docstring_sections = class.docstring.parsed %}
- {% include "docstring.html" with context %}
- {% endwith %}
- {% if config.merge_init_into_class %}
- {% if "__init__" in class.all_members and class.all_members["__init__"].has_docstring %}
- {% with docstring_sections = class.all_members["__init__"].docstring.parsed %}
- {% include "docstring.html" with context %}
- {% endwith %}
- {% endif %}
- {% endif %}
- {% endblock docstring %}
-
- {% block source scoped %}
- {% if config.show_source %}
- {% if config.merge_init_into_class %}
- {% if "__init__" in class.all_members and class.all_members["__init__"].source %}
- {% with init = class.all_members["__init__"] %}
-
- Source code in
- {%- if init.relative_filepath.is_absolute() -%}
- {{ init.relative_package_filepath }}
- {%- else -%}
- {{ init.relative_filepath }}
- {%- endif -%}
-
- {{ init.source|highlight(language="python", linestart=init.lineno, linenums=True) }}
-
- {% endwith %}
- {% endif %}
- {% elif class.source %}
-
- Source code in
- {%- if class.relative_filepath.is_absolute() -%}
- {{ class.relative_package_filepath }}
- {%- else -%}
- {{ class.relative_filepath }}
- {%- endif -%}
-
- {{ class.source|highlight(language="python", linestart=class.lineno, linenums=True) }}
-
- {% endif %}
- {% endif %}
- {% endblock source %}
-
- {% block children scoped %}
- {% set root = False %}
- {% set heading_level = heading_level + 1 %}
- {% include "children.html" with context %}
- {% endblock children %}
- {% endblock contents %}
-
-
-{% endwith %}
-
-
+ {% with obj = class, html_id = class.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 class_name = class.path if show_full_path else class.name %}
+
+ {% if not root or config.show_root_heading %}
+ {% filter heading(
+ heading_level,
+ role="class",
+ id=html_id,
+ class="doc doc-heading",
+ toc_label=('
'|safe if config.show_symbol_type_toc else '') + class.name,
+ ) %}
+
+ {% block heading scoped %}
+ {#- Heading block.
+
+ This block renders the heading for the class.
+ -#}
+ {% if config.show_symbol_type_heading %}
{% endif %}
+ {% if config.separate_signature %}
+
{{ class_name }}
+ {% elif config.merge_init_into_class and "__init__" in class.all_members %}
+ {% with function = class.all_members["__init__"] %}
+ {%+ filter highlight(language="python", inline=True) %}
+ {{ class_name }}{% include "signature"|get_template with context %}
+ {% endfilter %}
+ {% endwith %}
+ {% else %}
+
{{ class_name }}
+ {% endif %}
+ {% endblock heading %}
+
+ {% block labels scoped %}
+ {#- Labels block.
+
+ This block renders the labels for the class.
+ -#}
+ {% with labels = class.labels %}
+ {% include "labels"|get_template with context %}
+ {% endwith %}
+ {% endblock labels %}
+
+ {% endfilter %}
+
+ {% block signature scoped %}
+ {#- Signature block.
+
+ This block renders the signature for the class.
+ -#}
+ {% if config.separate_signature and config.merge_init_into_class %}
+ {% if "__init__" in class.all_members %}
+ {% with function = class.all_members["__init__"] %}
+ {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %}
+ {{ class.name }}
+ {% endfilter %}
+ {% endwith %}
+ {% endif %}
+ {% endif %}
+ {% endblock signature %}
+
+ {% else %}
+ {% if config.show_root_toc_entry %}
+ {% filter heading(heading_level,
+ role="class",
+ id=html_id,
+ toc_label=('
'|safe if config.show_symbol_type_toc else '') + class.name,
+ hidden=True,
+ ) %}
+ {% endfilter %}
+ {% endif %}
+ {% set heading_level = heading_level - 1 %}
+ {% endif %}
+
+
+ {% block contents scoped %}
+ {#- Contents block.
+
+ This block renders the contents of the class.
+ It contains other blocks that users can override.
+ Overriding the contents block allows to rearrange the order of the blocks.
+ -#}
+ {% block bases scoped %}
+ {#- Class bases block.
+
+ This block renders the bases for the class.
+ -#}
+ {% if config.show_bases and class.bases %}
+
+ Bases: {% for expression in class.bases -%}
+ {% include "expression"|get_template with context %}{% if not loop.last %}, {% endif %}
+ {% endfor -%}
+
+ {% endif %}
+ {% endblock bases %}
+
+ {% block docstring scoped %}
+ {#- Docstring block.
+
+ This block renders the docstring for the class.
+ -#}
+ {% with docstring_sections = class.docstring.parsed %}
+ {% include "docstring"|get_template with context %}
+ {% endwith %}
+ {% if config.merge_init_into_class %}
+ {% if "__init__" in class.all_members and class.all_members["__init__"].has_docstring %}
+ {% with docstring_sections = class.all_members["__init__"].docstring.parsed %}
+ {% include "docstring"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ {% endif %}
+ {% endblock docstring %}
+
+ {% block source scoped %}
+ {#- Source block.
+
+ This block renders the source code for the class.
+ -#}
+ {% if config.show_source %}
+ {% if config.merge_init_into_class %}
+ {% if "__init__" in class.all_members and class.all_members["__init__"].source %}
+ {% with init = class.all_members["__init__"] %}
+
+ Source code in
+ {%- if init.relative_filepath.is_absolute() -%}
+ {{ init.relative_package_filepath }}
+ {%- else -%}
+ {{ init.relative_filepath }}
+ {%- endif -%}
+
+ {{ init.source|highlight(language="python", linestart=init.lineno, linenums=True) }}
+
+ {% endwith %}
+ {% endif %}
+ {% elif class.source %}
+
+ Source code in
+ {%- if class.relative_filepath.is_absolute() -%}
+ {{ class.relative_package_filepath }}
+ {%- else -%}
+ {{ class.relative_filepath }}
+ {%- endif -%}
+
+ {{ class.source|highlight(language="python", linestart=class.lineno, linenums=True) }}
+
+ {% endif %}
+ {% endif %}
+ {% endblock source %}
+
+ {% block children scoped %}
+ {#- Children block.
+
+ This block renders the children (members) of the class.
+ -#}
+ {% set root = False %}
+ {% set heading_level = heading_level + 1 %}
+ {% include "children"|get_template with context %}
+ {% endblock children %}
+ {% endblock contents %}
+
+
+ {% endwith %}
+
- {{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True) }}
- {{ section.value.contents|convert_markdown(heading_level, html_id) }}
-
\ No newline at end of file
+{% extends "_base/docstring/admonition.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/admonition.html' is deprecated, extend '_base/docstring/admonition.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html.jinja
new file mode 100644
index 00000000..e3400280
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html.jinja
@@ -0,0 +1,20 @@
+{#- Template for admonitions in docstrings.
+
+This template renders admonitions using the `details` HTML element.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAdmonition): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering admonition") }}
+{% endblock logs %}
+
+
+ {{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True) }}
+ {{ section.value.contents|convert_markdown(heading_level, html_id) }}
+
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html
index 771a9eed..cd4b05be 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html
@@ -1,90 +1,11 @@
-{{ log.debug("Rendering attributes section") }}
+{% extends "_base/docstring/attributes.html.jinja" %}
-{% import "language.html" as lang with context %}
-
-{% if config.docstring_section_style == "table" %}
- {% block table_style scoped %}
- {{ section.title or lang.t("Attributes:") }}
-
-
-
- | {{ lang.t("Name") }} |
- {{ lang.t("Type") }} |
- {{ lang.t("Description") }} |
-
-
-
- {% for attribute in section.value %}
-
- {{ attribute.name }} |
-
- {% if attribute.annotation %}
- {% with expression = attribute.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
-
-
- {{ attribute.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% endfor %}
-
-
- {% endblock table_style %}
-{% elif config.docstring_section_style == "list" %}
- {% block list_style scoped %}
- {{ section.title or lang.t("Attributes:") }}
-
- {% endblock list_style %}
-{% elif config.docstring_section_style == "spacy" %}
- {% block spacy_style scoped %}
-
-
-
- | {{ (section.title or lang.t("ATTRIBUTE")).rstrip(":").upper() }} |
- {{ lang.t("DESCRIPTION") }} |
-
-
-
- {% for attribute in section.value %}
-
- {{ attribute.name }} |
-
-
- {{ attribute.description|convert_markdown(heading_level, html_id) }}
-
-
- {% if attribute.annotation %}
-
- TYPE:
- {% with expression = attribute.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- {% endif %}
-
- |
-
- {% endfor %}
-
-
- {% endblock spacy_style %}
-{% endif %}
\ No newline at end of file
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/attributes.html' is deprecated, extend '_base/docstring/attributes.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja
new file mode 100644
index 00000000..e6c03dee
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja
@@ -0,0 +1,109 @@
+{#- Template for "Attributes" sections in docstrings.
+
+This template renders a list of documented attributes in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering attributes section") }}
+{% endblock logs %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+{% if config.docstring_section_style == "table" %}
+ {% block table_style scoped %}
+ {#- Block for the `table` section style. -#}
+ {{ section.title or lang.t("Attributes:") }}
+
+
+
+ | {{ lang.t("Name") }} |
+ {{ lang.t("Type") }} |
+ {{ lang.t("Description") }} |
+
+
+
+ {% for attribute in section.value %}
+
+ {{ attribute.name }} |
+
+ {% if attribute.annotation %}
+ {% with expression = attribute.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ attribute.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% endfor %}
+
+
+ {% endblock table_style %}
+{% elif config.docstring_section_style == "list" %}
+ {% block list_style scoped %}
+ {#- Block for the `list` section style. -#}
+ {{ section.title or lang.t("Attributes:") }}
+
+ {% endblock list_style %}
+{% elif config.docstring_section_style == "spacy" %}
+ {% block spacy_style scoped %}
+ {#- Block for the `spacy` section style. -#}
+
+
+
+ | {{ (section.title or lang.t("ATTRIBUTE")).rstrip(":").upper() }} |
+ {{ lang.t("DESCRIPTION") }} |
+
+
+
+ {% for attribute in section.value %}
+
+ {{ attribute.name }} |
+
+
+ {{ attribute.description|convert_markdown(heading_level, html_id) }}
+
+
+ {% if attribute.annotation %}
+
+ TYPE:
+ {% with expression = attribute.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+ {% endif %}
+
+ |
+
+ {% endfor %}
+
+
+ {% endblock spacy_style %}
+{% endif %}
\ No newline at end of file
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html
index 054cf5af..78b47e2d 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html
@@ -1,67 +1,11 @@
-{{ log.debug("Rendering classes section") }}
+{% extends "_base/docstring/classes.html.jinja" %}
-{% import "language.html" as lang with context %}
-
-{% if config.docstring_section_style == "table" %}
- {% block table_style scoped %}
- {{ section.title or lang.t("Classes:") }}
-
-
-
- | {{ lang.t("Name") }} |
- {{ lang.t("Description") }} |
-
-
-
- {% for class in section.value %}
-
- {{ class.name }} |
-
-
- {{ class.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% endfor %}
-
-
- {% endblock table_style %}
-{% elif config.docstring_section_style == "list" %}
- {% block list_style scoped %}
- {{ section.title or lang.t("Classes:") }}
-
- {% endblock list_style %}
-{% elif config.docstring_section_style == "spacy" %}
- {% block spacy_style scoped %}
-
-
-
- | {{ (section.title or lang.t("CLASS")).rstrip(":").upper() }} |
- {{ lang.t("DESCRIPTION") }} |
-
-
-
- {% for class in section.value %}
-
- {{ class.name }} |
-
-
- {{ class.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% endfor %}
-
-
- {% endblock spacy_style %}
-{% endif %}
\ No newline at end of file
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/classes.html' is deprecated, extend '_base/docstring/classes.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja
new file mode 100644
index 00000000..1aee5fd2
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja
@@ -0,0 +1,86 @@
+{#- Template for "Classes" sections in docstrings.
+
+This template renders a list of documented classes in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering classes section") }}
+{% endblock logs %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+{% if config.docstring_section_style == "table" %}
+ {% block table_style scoped %}
+ {#- Block for the `table` section style. -#}
+ {{ section.title or lang.t("Classes:") }}
+
+
+
+ | {{ lang.t("Name") }} |
+ {{ lang.t("Description") }} |
+
+
+
+ {% for class in section.value %}
+
+ {{ class.name }} |
+
+
+ {{ class.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% endfor %}
+
+
+ {% endblock table_style %}
+{% elif config.docstring_section_style == "list" %}
+ {% block list_style scoped %}
+ {#- Block for the `list` section style. -#}
+ {{ section.title or lang.t("Classes:") }}
+
+ {% endblock list_style %}
+{% elif config.docstring_section_style == "spacy" %}
+ {% block spacy_style scoped %}
+ {#- Block for the `spacy` section style. -#}
+
+
+
+ | {{ (section.title or lang.t("CLASS")).rstrip(":").upper() }} |
+ {{ lang.t("DESCRIPTION") }} |
+
+
+
+ {% for class in section.value %}
+
+ {{ class.name }} |
+
+
+ {{ class.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% endfor %}
+
+
+ {% endblock spacy_style %}
+{% endif %}
\ No newline at end of file
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html
index 5305efa9..37674811 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html
@@ -1,12 +1,11 @@
-{{ log.debug("Rendering examples section") }}
+{% extends "_base/docstring/examples.html.jinja" %}
-{% import "language.html" as lang with context %}
-
-{{ section.title or lang.t("Examples:") }}
-{% for section_type, sub_section in section.value %}
- {% if section_type.value == "text" %}
- {{ sub_section|convert_markdown(heading_level, html_id) }}
- {% elif section_type.value == "examples" %}
- {{ sub_section|highlight(language="pycon", linenums=False) }}
- {% endif %}
-{% endfor %}
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/examples.html' is deprecated, extend '_base/docstring/examples.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja
new file mode 100644
index 00000000..48913f80
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja
@@ -0,0 +1,28 @@
+{#- Template for "Examples" sections in docstrings.
+
+This template renders a list of documented examples.
+It alternates between rendering text and code examples.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering examples section") }}
+{% endblock logs %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+{{ section.title or lang.t("Examples:") }}
+{% for section_type, sub_section in section.value %}
+ {% if section_type.value == "text" %}
+ {{ sub_section|convert_markdown(heading_level, html_id) }}
+ {% elif section_type.value == "examples" %}
+ {{ sub_section|highlight(language="pycon", linenums=False) }}
+ {% endif %}
+{% endfor %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html
index a16917bd..a61c48fb 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html
@@ -1,73 +1,11 @@
-{{ log.debug("Rendering functions section") }}
+{% extends "_base/docstring/functions.html.jinja" %}
-{% import "language.html" as lang with context %}
-
-{% if config.docstring_section_style == "table" %}
- {% block table_style scoped %}
- {{ section.title or lang.t("Methods:") if obj.is_class else lang.t("Functions:") }}
-
-
-
- | {{ lang.t("Name") }} |
- {{ lang.t("Description") }} |
-
-
-
- {% for function in section.value %}
- {% if not function.name == "__init__" or not config.merge_init_into_class %}
-
- {{ function.name }} |
-
-
- {{ function.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% endif %}
- {% endfor %}
-
-
- {% endblock table_style %}
-{% elif config.docstring_section_style == "list" %}
- {% block list_style scoped %}
- {{ section.title or lang.t("Methods:") if obj.is_class else lang.t("Functions:") }}
-
- {% endblock list_style %}
-{% elif config.docstring_section_style == "spacy" %}
- {% block spacy_style scoped %}
-
-
-
- | {{ (section.title or lang.t("METHOD") if obj.is_class else lang.t("FUNCTION")).rstrip(":").upper() }} |
- {{ lang.t("DESCRIPTION") }} |
-
-
-
- {% for function in section.value %}
- {% if not function.name == "__init__" or not config.merge_init_into_class %}
-
- {{ function.name }} |
-
-
- {{ function.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% endif %}
- {% endfor %}
-
-
- {% endblock spacy_style %}
-{% endif %}
\ No newline at end of file
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/functions.html' is deprecated, extend '_base/docstring/functions.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja
new file mode 100644
index 00000000..53bda233
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja
@@ -0,0 +1,92 @@
+{#- Template for "Functions" sections in docstrings.
+
+This template renders a list of documented functions in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering functions section") }}
+{% endblock logs %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+{% if config.docstring_section_style == "table" %}
+ {% block table_style scoped %}
+ {#- Block for the `table` section style. -#}
+ {{ section.title or lang.t("Methods:") if obj.is_class else lang.t("Functions:") }}
+
+
+
+ | {{ lang.t("Name") }} |
+ {{ lang.t("Description") }} |
+
+
+
+ {% for function in section.value %}
+ {% if not function.name == "__init__" or not config.merge_init_into_class %}
+
+ {{ function.name }} |
+
+
+ {{ function.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% endif %}
+ {% endfor %}
+
+
+ {% endblock table_style %}
+{% elif config.docstring_section_style == "list" %}
+ {% block list_style scoped %}
+ {#- Block for the `list` section style. -#}
+ {{ section.title or lang.t("Methods:") if obj.is_class else lang.t("Functions:") }}
+
+ {% endblock list_style %}
+{% elif config.docstring_section_style == "spacy" %}
+ {% block spacy_style scoped %}
+ {#- Block for the `spacy` section style. -#}
+
+
+
+ | {{ (section.title or lang.t("METHOD") if obj.is_class else lang.t("FUNCTION")).rstrip(":").upper() }} |
+ {{ lang.t("DESCRIPTION") }} |
+
+
+
+ {% for function in section.value %}
+ {% if not function.name == "__init__" or not config.merge_init_into_class %}
+
+ {{ function.name }} |
+
+
+ {{ function.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% endif %}
+ {% endfor %}
+
+
+ {% endblock spacy_style %}
+{% endif %}
\ No newline at end of file
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html
index 26b38257..d0b303b4 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html
@@ -1,67 +1,11 @@
-{{ log.debug("Rendering modules section") }}
+{% extends "_base/docstring/modules.html.jinja" %}
-{% import "language.html" as lang with context %}
-
-{% if config.docstring_section_style == "table" %}
- {% block table_style scoped %}
- {{ section.title or lang.t("Modules:") }}
-
-
-
- | {{ lang.t("Name") }} |
- {{ lang.t("Description") }} |
-
-
-
- {% for module in section.value %}
-
- {{ module.name }} |
-
-
- {{ module.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% endfor %}
-
-
- {% endblock table_style %}
-{% elif config.docstring_section_style == "list" %}
- {% block list_style scoped %}
- {{ section.title or lang.t("Modules:") }}
-
- {% endblock list_style %}
-{% elif config.docstring_section_style == "spacy" %}
- {% block spacy_style scoped %}
-
-
-
- | {{ (section.title or lang.t("MODULE")).rstrip(":").upper() }} |
- {{ lang.t("DESCRIPTION") }} |
-
-
-
- {% for module in section.value %}
-
- {{ module.name }} |
-
-
- {{ module.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% endfor %}
-
-
- {% endblock spacy_style %}
-{% endif %}
\ No newline at end of file
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/modules.html' is deprecated, extend '_base/docstring/modules.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja
new file mode 100644
index 00000000..239f7a55
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja
@@ -0,0 +1,86 @@
+{#- Template for "Modules" sections in docstrings.
+
+This template renders a list of documented modules in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering modules section") }}
+{% endblock logs %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+{% if config.docstring_section_style == "table" %}
+ {% block table_style scoped %}
+ {#- Block for the `table` section style. -#}
+ {{ section.title or lang.t("Modules:") }}
+
+
+
+ | {{ lang.t("Name") }} |
+ {{ lang.t("Description") }} |
+
+
+
+ {% for module in section.value %}
+
+ {{ module.name }} |
+
+
+ {{ module.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% endfor %}
+
+
+ {% endblock table_style %}
+{% elif config.docstring_section_style == "list" %}
+ {% block list_style scoped %}
+ {#- Block for the `list` section style. -#}
+ {{ section.title or lang.t("Modules:") }}
+
+ {% endblock list_style %}
+{% elif config.docstring_section_style == "spacy" %}
+ {% block spacy_style scoped %}
+ {#- Block for the `spacy` section style. -#}
+
+
+
+ | {{ (section.title or lang.t("MODULE")).rstrip(":").upper() }} |
+ {{ lang.t("DESCRIPTION") }} |
+
+
+
+ {% for module in section.value %}
+
+ {{ module.name }} |
+
+
+ {{ module.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% endfor %}
+
+
+ {% endblock spacy_style %}
+{% endif %}
\ No newline at end of file
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html
index f31836a8..eae60aa7 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html
@@ -1,90 +1,11 @@
-{{ log.debug("Rendering other parameters section") }}
+{% extends "_base/docstring/other_parameters.html.jinja" %}
-{% import "language.html" as lang with context %}
-
-{% if config.docstring_section_style == "table" %}
- {% block table_style scoped %}
- {{ section.title or lang.t("Other Parameters:") }}
-
-
-
- | {{ lang.t("Name") }} |
- {{ lang.t("Type") }} |
- {{ lang.t("Description") }} |
-
-
-
- {% for parameter in section.value %}
-
- {{ parameter.name }} |
-
- {% if parameter.annotation %}
- {% with expression = parameter.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
-
-
- {{ parameter.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% endfor %}
-
-
- {% endblock table_style %}
-{% elif config.docstring_section_style == "list" %}
- {% block list_style scoped %}
- {{ section.title or lang.t("Other Parameters:") }}
-
- {% endblock list_style %}
-{% elif config.docstring_section_style == "spacy" %}
- {% block spacy_style scoped %}
-
-
-
- | {{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }} |
- {{ lang.t("DESCRIPTION") }} |
-
-
-
- {% for parameter in section.value %}
-
- {{ parameter.name }} |
-
-
- {{ parameter.description|convert_markdown(heading_level, html_id) }}
-
-
- {% if parameter.annotation %}
-
- {{ lang.t("TYPE:") }}
- {% with expression = parameter.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- {% endif %}
-
- |
-
- {% endfor %}
-
-
- {% endblock spacy_style %}
-{% endif %}
\ No newline at end of file
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/other_parameters.html' is deprecated, extend '_base/docstring/other_parameters.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html.jinja
new file mode 100644
index 00000000..7daabeda
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html.jinja
@@ -0,0 +1,109 @@
+{#- Template for "Other parameters" sections in docstrings.
+
+This template renders a list of documented other parameters in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering other parameters section") }}
+{% endblock logs %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+{% if config.docstring_section_style == "table" %}
+ {% block table_style scoped %}
+ {#- Block for the `table` section style. -#}
+ {{ section.title or lang.t("Other Parameters:") }}
+
+
+
+ | {{ lang.t("Name") }} |
+ {{ lang.t("Type") }} |
+ {{ lang.t("Description") }} |
+
+
+
+ {% for parameter in section.value %}
+
+ {{ parameter.name }} |
+
+ {% if parameter.annotation %}
+ {% with expression = parameter.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ parameter.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% endfor %}
+
+
+ {% endblock table_style %}
+{% elif config.docstring_section_style == "list" %}
+ {% block list_style scoped %}
+ {#- Block for the `list` section style. -#}
+ {{ section.title or lang.t("Other Parameters:") }}
+
+ {% endblock list_style %}
+{% elif config.docstring_section_style == "spacy" %}
+ {% block spacy_style scoped %}
+ {#- Block for the `spacy` section style. -#}
+
+
+
+ | {{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }} |
+ {{ lang.t("DESCRIPTION") }} |
+
+
+
+ {% for parameter in section.value %}
+
+ {{ parameter.name }} |
+
+
+ {{ parameter.description|convert_markdown(heading_level, html_id) }}
+
+
+ {% if parameter.annotation %}
+
+ {{ lang.t("TYPE:") }}
+ {% with expression = parameter.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+ {% endif %}
+
+ |
+
+ {% endfor %}
+
+
+ {% endblock spacy_style %}
+{% endif %}
\ No newline at end of file
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html
index 05bdadee..f5745464 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html
@@ -1,113 +1,11 @@
-{{ log.debug("Rendering parameters section") }}
+{% extends "_base/docstring/parameters.html.jinja" %}
-{% import "language.html" as lang with context %}
-
-{% if config.docstring_section_style == "table" %}
- {% block table_style scoped %}
- {{ section.title or lang.t("Parameters:") }}
-
-
-
- | {{ lang.t("Name") }} |
- {{ lang.t("Type") }} |
- {{ lang.t("Description") }} |
- {{ lang.t("Default") }} |
-
-
-
- {% for parameter in section.value %}
-
- {{ parameter.name }} |
-
- {% if parameter.annotation %}
- {% with expression = parameter.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
-
-
- {{ parameter.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% if parameter.default %}
- {% with expression = parameter.default %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% else %}
- {{ lang.t("required") }}
- {% endif %}
- |
-
- {% endfor %}
-
-
- {% endblock table_style %}
-{% elif config.docstring_section_style == "list" %}
- {% block list_style scoped %}
- {{ section.title or lang.t("Parameters:") }}
-
- {% endblock list_style %}
-{% elif config.docstring_section_style == "spacy" %}
- {% block spacy_style scoped %}
-
-
-
- | {{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }} |
- {{ lang.t("DESCRIPTION") }} |
-
-
-
- {% for parameter in section.value %}
-
- {{ parameter.name }} |
-
-
- {{ parameter.description|convert_markdown(heading_level, html_id) }}
-
-
- {% if parameter.annotation %}
-
- {{ lang.t("TYPE:") }}
- {% with expression = parameter.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- {% endif %}
- {% if parameter.default %}
-
- {{ lang.t("DEFAULT:") }}
- {% with expression = parameter.default %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- {% endif %}
-
- |
-
- {% endfor %}
-
-
- {% endblock spacy_style %}
-{% endif %}
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/parameters.html' is deprecated, extend '_base/docstring/parameters.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja
new file mode 100644
index 00000000..3de6f4a9
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja
@@ -0,0 +1,132 @@
+{#- Template for "Parameters" sections in docstrings.
+
+This template renders a list of documented parameters in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering parameters section") }}
+{% endblock logs %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+{% if config.docstring_section_style == "table" %}
+ {% block table_style scoped %}
+ {#- Block for the `table` section style. -#}
+ {{ section.title or lang.t("Parameters:") }}
+
+
+
+ | {{ lang.t("Name") }} |
+ {{ lang.t("Type") }} |
+ {{ lang.t("Description") }} |
+ {{ lang.t("Default") }} |
+
+
+
+ {% for parameter in section.value %}
+
+ {{ parameter.name }} |
+
+ {% if parameter.annotation %}
+ {% with expression = parameter.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ parameter.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% if parameter.default %}
+ {% with expression = parameter.default %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% else %}
+ {{ lang.t("required") }}
+ {% endif %}
+ |
+
+ {% endfor %}
+
+
+ {% endblock table_style %}
+{% elif config.docstring_section_style == "list" %}
+ {% block list_style scoped %}
+ {#- Block for the `list` section style. -#}
+ {{ section.title or lang.t("Parameters:") }}
+
+ {% endblock list_style %}
+{% elif config.docstring_section_style == "spacy" %}
+ {% block spacy_style scoped %}
+ {#- Block for the `spacy` section style. -#}
+
+
+
+ | {{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }} |
+ {{ lang.t("DESCRIPTION") }} |
+
+
+
+ {% for parameter in section.value %}
+
+ {{ parameter.name }} |
+
+
+ {{ parameter.description|convert_markdown(heading_level, html_id) }}
+
+
+ {% if parameter.annotation %}
+
+ {{ lang.t("TYPE:") }}
+ {% with expression = parameter.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+ {% endif %}
+ {% if parameter.default %}
+
+ {{ lang.t("DEFAULT:") }}
+ {% with expression = parameter.default %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+ {% endif %}
+
+ |
+
+ {% endfor %}
+
+
+ {% endblock spacy_style %}
+{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html
index 5e20b653..361b9732 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html
@@ -1,83 +1,11 @@
-{{ log.debug("Rendering raises section") }}
+{% extends "_base/docstring/raises.html.jinja" %}
-{% import "language.html" as lang with context %}
-
-{% if config.docstring_section_style == "table" %}
- {% block table_style scoped %}
- {{ section.title or lang.t("Raises:") }}
-
-
-
- | {{ lang.t("Type") }} |
- {{ lang.t("Description") }} |
-
-
-
- {% for raises in section.value %}
-
-
- {% if raises.annotation %}
- {% with expression = raises.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
-
-
- {{ raises.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% endfor %}
-
-
- {% endblock table_style %}
-{% elif config.docstring_section_style == "list" %}
- {% block list_style scoped %}
- {{ lang.t(section.title) or lang.t("Raises:") }}
-
- {% endblock list_style %}
-{% elif config.docstring_section_style == "spacy" %}
- {% block spacy_style scoped %}
-
-
-
- | {{ (section.title or lang.t("RAISES")).rstrip(":").upper() }} |
- {{ lang.t("DESCRIPTION") }} |
-
-
-
- {% for raises in section.value %}
-
-
-
- {% with expression = raises.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- |
-
-
- {{ raises.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% endfor %}
-
-
- {% endblock spacy_style %}
-{% endif %}
\ No newline at end of file
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/raises.html' is deprecated, extend '_base/docstring/raises.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja
new file mode 100644
index 00000000..79024057
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja
@@ -0,0 +1,102 @@
+{#- Template for "Raises" sections in docstrings.
+
+This template renders a list of documented exceptions in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering raises section") }}
+{% endblock logs %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+{% if config.docstring_section_style == "table" %}
+ {% block table_style scoped %}
+ {#- Block for the `table` section style. -#}
+ {{ section.title or lang.t("Raises:") }}
+
+
+
+ | {{ lang.t("Type") }} |
+ {{ lang.t("Description") }} |
+
+
+
+ {% for raises in section.value %}
+
+
+ {% if raises.annotation %}
+ {% with expression = raises.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ raises.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% endfor %}
+
+
+ {% endblock table_style %}
+{% elif config.docstring_section_style == "list" %}
+ {% block list_style scoped %}
+ {#- Block for the `list` section style. -#}
+ {{ lang.t(section.title) or lang.t("Raises:") }}
+
+ {% endblock list_style %}
+{% elif config.docstring_section_style == "spacy" %}
+ {% block spacy_style scoped %}
+ {#- Block for the `spacy` section style. -#}
+
+
+
+ | {{ (section.title or lang.t("RAISES")).rstrip(":").upper() }} |
+ {{ lang.t("DESCRIPTION") }} |
+
+
+
+ {% for raises in section.value %}
+
+
+
+ {% with expression = raises.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+ |
+
+
+ {{ raises.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% endfor %}
+
+
+ {% endblock spacy_style %}
+{% endif %}
\ No newline at end of file
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html
index e03e8b8e..e5a115c1 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html
@@ -1,103 +1,11 @@
-{{ log.debug("Rendering receives section") }}
+{% extends "_base/docstring/receives.html.jinja" %}
-{% import "language.html" as lang with context %}
-
-{% if config.docstring_section_style == "table" %}
- {% block table_style scoped %}
- {% set name_column = section.value|selectattr("name")|any %}
- {{ section.title or lang.t("Receives:") }}
-
-
-
- {% if name_column %}| {{ lang.t("Name") }} | {% endif %}
- {{ lang.t("Type") }} |
- {{ lang.t("Description") }} |
-
-
-
- {% for receives in section.value %}
-
- {% if name_column %}{% if receives.name %}{{ receives.name }}{% endif %} | {% endif %}
-
- {% if receives.annotation %}
- {% with expression = receives.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
-
-
- {{ receives.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% endfor %}
-
-
- {% endblock table_style %}
-{% elif config.docstring_section_style == "list" %}
- {% block list_style scoped %}
- {{ section.title or lang.t("Receives:") }}
-
- {% endblock list_style %}
-{% elif config.docstring_section_style == "spacy" %}
- {% block spacy_style scoped %}
-
-
-
- | {{ (section.title or lang.t("RECEIVES")).rstrip(":").upper() }} |
- {{ lang.t("DESCRIPTION") }} |
-
-
-
- {% for receives in section.value %}
-
-
- {% if receives.name %}
- {{ receives.name }}
- {% elif receives.annotation %}
-
- {% with expression = receives.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- {% endif %}
- |
-
-
- {{ receives.description|convert_markdown(heading_level, html_id) }}
-
- {% if receives.name and receives.annotation %}
-
-
- {{ lang.t("TYPE:") }}
- {% with expression = receives.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
-
- {% endif %}
- |
-
- {% endfor %}
-
-
- {% endblock spacy_style %}
-{% endif %}
\ No newline at end of file
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/receives.html' is deprecated, extend '_base/docstring/receives.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html.jinja
new file mode 100644
index 00000000..2fcce8ef
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html.jinja
@@ -0,0 +1,122 @@
+{#- Template for "Receives" sections in docstrings.
+
+This template renders a list of documented received values (generators) in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering receives section") }}
+{% endblock logs %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+{% if config.docstring_section_style == "table" %}
+ {% block table_style scoped %}
+ {#- Block for the `table` section style. -#}
+ {% set name_column = section.value|selectattr("name")|any %}
+ {{ section.title or lang.t("Receives:") }}
+
+
+
+ {% if name_column %}| {{ lang.t("Name") }} | {% endif %}
+ {{ lang.t("Type") }} |
+ {{ lang.t("Description") }} |
+
+
+
+ {% for receives in section.value %}
+
+ {% if name_column %}{% if receives.name %}{{ receives.name }}{% endif %} | {% endif %}
+
+ {% if receives.annotation %}
+ {% with expression = receives.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ receives.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% endfor %}
+
+
+ {% endblock table_style %}
+{% elif config.docstring_section_style == "list" %}
+ {% block list_style scoped %}
+ {#- Block for the `list` section style. -#}
+ {{ section.title or lang.t("Receives:") }}
+
+ {% endblock list_style %}
+{% elif config.docstring_section_style == "spacy" %}
+ {% block spacy_style scoped %}
+ {#- Block for the `spacy` section style. -#}
+
+
+
+ | {{ (section.title or lang.t("RECEIVES")).rstrip(":").upper() }} |
+ {{ lang.t("DESCRIPTION") }} |
+
+
+
+ {% for receives in section.value %}
+
+
+ {% if receives.name %}
+ {{ receives.name }}
+ {% elif receives.annotation %}
+
+ {% with expression = receives.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+ {% endif %}
+ |
+
+
+ {{ receives.description|convert_markdown(heading_level, html_id) }}
+
+ {% if receives.name and receives.annotation %}
+
+
+ {{ lang.t("TYPE:") }}
+ {% with expression = receives.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+
+ {% endif %}
+ |
+
+ {% endfor %}
+
+
+ {% endblock spacy_style %}
+{% endif %}
\ No newline at end of file
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html
index a7a7cb98..0e7807ac 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html
@@ -1,103 +1,11 @@
-{{ log.debug("Rendering returns section") }}
+{% extends "_base/docstring/returns.html.jinja" %}
-{% import "language.html" as lang with context %}
-
-{% if config.docstring_section_style == "table" %}
- {% block table_style scoped %}
- {% set name_column = section.value|selectattr("name")|any %}
- {{ section.title or lang.t("Returns:") }}
-
-
-
- {% if name_column %}| {{ lang.t("Name") }} | {% endif %}
- {{ lang.t("Type") }} |
- {{ lang.t("Description") }} |
-
-
-
- {% for returns in section.value %}
-
- {% if name_column %}{% if returns.name %}{{ returns.name }}{% endif %} | {% endif %}
-
- {% if returns.annotation %}
- {% with expression = returns.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
-
-
- {{ returns.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% endfor %}
-
-
- {% endblock table_style %}
-{% elif config.docstring_section_style == "list" %}
- {% block list_style scoped %}
- {{ section.title or lang.t("Returns:") }}
-
- {% endblock list_style %}
-{% elif config.docstring_section_style == "spacy" %}
- {% block spacy_style scoped %}
-
-
-
- | {{ (section.title or lang.t("RETURNS")).rstrip(":").upper() }} |
- {{ lang.t("DESCRIPTION").upper() }} |
-
-
-
- {% for returns in section.value %}
-
-
- {% if returns.name %}
- {{ returns.name }}
- {% elif returns.annotation %}
-
- {% with expression = returns.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- {% endif %}
- |
-
-
- {{ returns.description|convert_markdown(heading_level, html_id) }}
-
- {% if returns.name and returns.annotation %}
-
-
- {{ lang.t("TYPE:") }}
- {% with expression = returns.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
-
- {% endif %}
- |
-
- {% endfor %}
-
-
- {% endblock spacy_style %}
-{% endif %}
\ No newline at end of file
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/returns.html' is deprecated, extend '_base/docstring/returns.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html.jinja
new file mode 100644
index 00000000..8feeb054
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html.jinja
@@ -0,0 +1,122 @@
+{#- Template for "Returns" sections in docstrings.
+
+This template renders a list of documented returned values in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering returns section") }}
+{% endblock logs %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+{% if config.docstring_section_style == "table" %}
+ {% block table_style scoped %}
+ {#- Block for the `table` section style. -#}
+ {% set name_column = section.value|selectattr("name")|any %}
+ {{ section.title or lang.t("Returns:") }}
+
+
+
+ {% if name_column %}| {{ lang.t("Name") }} | {% endif %}
+ {{ lang.t("Type") }} |
+ {{ lang.t("Description") }} |
+
+
+
+ {% for returns in section.value %}
+
+ {% if name_column %}{% if returns.name %}{{ returns.name }}{% endif %} | {% endif %}
+
+ {% if returns.annotation %}
+ {% with expression = returns.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ returns.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% endfor %}
+
+
+ {% endblock table_style %}
+{% elif config.docstring_section_style == "list" %}
+ {% block list_style scoped %}
+ {#- Block for the `list` section style. -#}
+ {{ section.title or lang.t("Returns:") }}
+
+ {% endblock list_style %}
+{% elif config.docstring_section_style == "spacy" %}
+ {% block spacy_style scoped %}
+ {#- Block for the `spacy` section style. -#}
+
+
+
+ | {{ (section.title or lang.t("RETURNS")).rstrip(":").upper() }} |
+ {{ lang.t("DESCRIPTION").upper() }} |
+
+
+
+ {% for returns in section.value %}
+
+
+ {% if returns.name %}
+ {{ returns.name }}
+ {% elif returns.annotation %}
+
+ {% with expression = returns.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+ {% endif %}
+ |
+
+
+ {{ returns.description|convert_markdown(heading_level, html_id) }}
+
+ {% if returns.name and returns.annotation %}
+
+
+ {{ lang.t("TYPE:") }}
+ {% with expression = returns.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+
+ {% endif %}
+ |
+
+ {% endfor %}
+
+
+ {% endblock spacy_style %}
+{% endif %}
\ No newline at end of file
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html
index a9bdae26..b7b937a9 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html
@@ -1,83 +1,11 @@
-{{ log.debug("Rendering warns section") }}
+{% extends "_base/docstring/warns.html.jinja" %}
-{% import "language.html" as lang with context %}
-
-{% if config.docstring_section_style == "table" %}
- {% block table_style scoped %}
- {{ section.title or lang.t("Warns:") }}
-
-
-
- | {{ lang.t("Type") }} |
- {{ lang.t("Description") }} |
-
-
-
- {% for warns in section.value %}
-
-
- {% if warns.annotation %}
- {% with expression = warns.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
-
-
- {{ warns.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% endfor %}
-
-
- {% endblock table_style %}
-{% elif config.docstring_section_style == "list" %}
- {% block list_style scoped %}
- {{ section.title or lang.t("Warns:") }}
-
- {% endblock list_style %}
-{% elif config.docstring_section_style == "spacy" %}
- {% block spacy_style scoped %}
-
-
-
- | {{ (section.title or lang.t("WARNS")).rstrip(":").upper() }} |
- {{ lang.t("DESCRIPTION") }} |
-
-
-
- {% for warns in section.value %}
-
-
-
- {% with expression = warns.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- |
-
-
- {{ warns.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% endfor %}
-
-
- {% endblock spacy_style %}
-{% endif %}
\ No newline at end of file
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/warns.html' is deprecated, extend '_base/docstring/warns.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html.jinja
new file mode 100644
index 00000000..6143257d
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html.jinja
@@ -0,0 +1,102 @@
+{#- Template for "Warns" sections in docstrings.
+
+This template renders a list of documented warnings in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering warns section") }}
+{% endblock logs %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+{% if config.docstring_section_style == "table" %}
+ {% block table_style scoped %}
+ {#- Block for the `table` section style. -#}
+ {{ section.title or lang.t("Warns:") }}
+
+
+
+ | {{ lang.t("Type") }} |
+ {{ lang.t("Description") }} |
+
+
+
+ {% for warns in section.value %}
+
+
+ {% if warns.annotation %}
+ {% with expression = warns.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ warns.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% endfor %}
+
+
+ {% endblock table_style %}
+{% elif config.docstring_section_style == "list" %}
+ {% block list_style scoped %}
+ {#- Block for the `list` section style. -#}
+ {{ section.title or lang.t("Warns:") }}
+
+ {% endblock list_style %}
+{% elif config.docstring_section_style == "spacy" %}
+ {% block spacy_style scoped %}
+ {#- Block for the `spacy` section style. -#}
+
+
+
+ | {{ (section.title or lang.t("WARNS")).rstrip(":").upper() }} |
+ {{ lang.t("DESCRIPTION") }} |
+
+
+
+ {% for warns in section.value %}
+
+
+
+ {% with expression = warns.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+ |
+
+
+ {{ warns.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% endfor %}
+
+
+ {% endblock spacy_style %}
+{% endif %}
\ No newline at end of file
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html
index 6c4cb0b0..ecd6f513 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html
@@ -1,103 +1,11 @@
-{{ log.debug("Rendering yields section") }}
+{% extends "_base/docstring/yields.html.jinja" %}
-{% import "language.html" as lang with context %}
-
-{% if config.docstring_section_style == "table" %}
- {% block table_style scoped %}
- {% set name_column = section.value|selectattr("name")|any %}
- {{ section.title or lang.t("Yields:") }}
-
-
-
- {% if name_column %}| {{ lang.t("Name") }} | {% endif %}
- {{ lang.t("Type") }} |
- {{ lang.t("Description") }} |
-
-
-
- {% for yields in section.value %}
-
- {% if name_column %}{% if yields.name %}{{ yields.name }}{% endif %} | {% endif %}
-
- {% if yields.annotation %}
- {% with expression = yields.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
-
-
- {{ yields.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% endfor %}
-
-
- {% endblock table_style %}
-{% elif config.docstring_section_style == "list" %}
- {% block list_style scoped %}
- {{ section.title or lang.t("Yields:") }}
-
- {% endblock list_style %}
-{% elif config.docstring_section_style == "spacy" %}
- {% block spacy_style scoped %}
-
-
-
- | {{ (section.title or lang.t("YIELDS")).rstrip(":").upper() }} |
- {{ lang.t("DESCRIPTION") }} |
-
-
-
- {% for yields in section.value %}
-
-
- {% if yields.name %}
- {{ yields.name }}
- {% elif yields.annotation %}
-
- {% with expression = yields.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- {% endif %}
- |
-
-
- {{ yields.description|convert_markdown(heading_level, html_id) }}
-
- {% if yields.name and yields.annotation %}
-
-
- {{ lang.t("TYPE:") }}:
- {% with expression = yields.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
-
- {% endif %}
- |
-
- {% endfor %}
-
-
- {% endblock spacy_style %}
-{% endif %}
\ No newline at end of file
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/yields.html' is deprecated, extend '_base/docstring/yields.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html.jinja
new file mode 100644
index 00000000..d326c1fe
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html.jinja
@@ -0,0 +1,122 @@
+{#- Template for "Yields" sections in docstrings.
+
+This template renders a list of documented yielded values (generators) in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering yields section") }}
+{% endblock logs %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+{% if config.docstring_section_style == "table" %}
+ {% block table_style scoped %}
+ {#- Block for the `table` section style. -#}
+ {% set name_column = section.value|selectattr("name")|any %}
+ {{ section.title or lang.t("Yields:") }}
+
+
+
+ {% if name_column %}| {{ lang.t("Name") }} | {% endif %}
+ {{ lang.t("Type") }} |
+ {{ lang.t("Description") }} |
+
+
+
+ {% for yields in section.value %}
+
+ {% if name_column %}{% if yields.name %}{{ yields.name }}{% endif %} | {% endif %}
+
+ {% if yields.annotation %}
+ {% with expression = yields.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ yields.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% endfor %}
+
+
+ {% endblock table_style %}
+{% elif config.docstring_section_style == "list" %}
+ {% block list_style scoped %}
+ {#- Block for the `list` section style. -#}
+ {{ section.title or lang.t("Yields:") }}
+
+ {% endblock list_style %}
+{% elif config.docstring_section_style == "spacy" %}
+ {% block spacy_style scoped %}
+ {#- Block for the `spacy` section style. -#}
+
+
+
+ | {{ (section.title or lang.t("YIELDS")).rstrip(":").upper() }} |
+ {{ lang.t("DESCRIPTION") }} |
+
+
+
+ {% for yields in section.value %}
+
+
+ {% if yields.name %}
+ {{ yields.name }}
+ {% elif yields.annotation %}
+
+ {% with expression = yields.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+ {% endif %}
+ |
+
+
+ {{ yields.description|convert_markdown(heading_level, html_id) }}
+
+ {% if yields.name and yields.annotation %}
+
+
+ {{ lang.t("TYPE:") }}:
+ {% with expression = yields.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+
+ {% endif %}
+ |
+
+ {% endfor %}
+
+
+ {% endblock spacy_style %}
+{% endif %}
\ No newline at end of file
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html
index 00e1c761..556b3e2b 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html
@@ -1,56 +1,11 @@
-{%- macro crossref(name, annotation_path) -%}
- {%- with full = name.canonical_path -%}
- {%- if annotation_path == "brief" -%}
- {%- set annotation = name.canonical_name -%}
- {%- elif annotation_path == "source" -%}
- {%- set annotation = name.name -%}
- {%- elif annotation_path == "full" -%}
- {%- set annotation = full -%}
- {%- endif -%}
- {%- for title, path in annotation|split_path(full) -%}
- {%- if not signature or config.signature_crossrefs -%}
- {%- filter stash_crossref(length=title|length) -%}
- {{ title }}
- {%- endfilter -%}
- {%- else -%}
- {{ title }}
- {%- endif -%}
- {%- if not loop.last -%}.{%- endif -%}
- {%- endfor -%}
- {%- endwith -%}
-{%- endmacro -%}
+{% extends "_base/expression.html.jinja" %}
-{%- macro render(expression, annotations_path) -%}
- {%- if expression is string -%}
- {%- if signature -%}{{ expression|safe }}{%- else -%}{{ expression }}{%- endif -%}
- {%- elif expression.classname == "ExprName" -%}
- {{ crossref(expression, annotations_path) }}
- {%- elif config.unwrap_annotated and expression.classname == "ExprSubscript" and expression.canonical_path in ("typing.Annotated", "typing_extensions.Annotated") -%}
- {{ render(expression.slice.elements[0], annotations_path) }}
- {%- elif expression.classname == "ExprAttribute" -%}
- {%- if annotations_path == "brief" -%}
- {%- if expression.last.is_enum_value -%}
- {{ crossref(expression.last.parent, "brief") }}.value
- {%- else -%}
- {{ render(expression.last, "brief") }}
- {%- endif -%}
- {%- elif annotations_path == "full" -%}
- {{ render(expression.first, "full") }}
- {%- for element in expression -%}
- {%- if not loop.first -%}
- {{ render(element, "brief") }}
- {%- endif -%}
- {%- endfor -%}
- {%- else -%}
- {%- for element in expression -%}
- {{ render(element, annotations_path) }}
- {%- endfor -%}
- {%- endif -%}
- {%- else -%}
- {%- for element in expression -%}
- {{ render(element, annotations_path) }}
- {%- endfor -%}
- {%- endif -%}
-{%- endmacro -%}
-
-{{ render(expression, config.annotations_path) }}
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/expression.html' is deprecated, extend '_base/expression.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja
new file mode 100644
index 00000000..5a216e3e
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja
@@ -0,0 +1,89 @@
+{#- Template for expressions.
+
+This template renders a Griffe expression,
+which is a tree-like structure representing a Python expression.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+{% endblock logs %}
+
+{%- macro crossref(name, annotation_path) -%}
+ {#- Output a cross-reference.
+
+ This macro outputs a cross-reference to the given name.
+
+ Parameters:
+ name (griffe.expressions.ExprName): The name to cross-reference.
+ annotation_path (str): Either "brief", "source", or "full".
+
+ Returns:
+ Either a cross-reference (using an autorefs span) or the name itself.
+ -#}
+ {%- with full = name.canonical_path -%}
+ {%- if annotation_path == "brief" -%}
+ {%- set annotation = name.canonical_name -%}
+ {%- elif annotation_path == "source" -%}
+ {%- set annotation = name.name -%}
+ {%- elif annotation_path == "full" -%}
+ {%- set annotation = full -%}
+ {%- endif -%}
+ {%- for title, path in annotation|split_path(full) -%}
+ {%- if not signature or config.signature_crossrefs -%}
+ {%- filter stash_crossref(length=title|length) -%}
+ {{ title }}
+ {%- endfilter -%}
+ {%- else -%}
+ {{ title }}
+ {%- endif -%}
+ {%- if not loop.last -%}.{%- endif -%}
+ {%- endfor -%}
+ {%- endwith -%}
+{%- endmacro -%}
+
+{%- macro render(expression, annotations_path) -%}
+ {#- Render an expression.
+
+ Parameters:
+ expression (griffe.expressions.Expr): The expression to render.
+ annotations_path (str): Either "brief", "source", or "full".
+
+ Returns:
+ The rendered expression.
+ -#}
+ {%- if expression is string -%}
+ {%- if signature -%}{{ expression|safe }}{%- else -%}{{ expression }}{%- endif -%}
+ {%- elif expression.classname == "ExprName" -%}
+ {{ crossref(expression, annotations_path) }}
+ {%- elif config.unwrap_annotated and expression.classname == "ExprSubscript" and expression.canonical_path in ("typing.Annotated", "typing_extensions.Annotated") -%}
+ {{ render(expression.slice.elements[0], annotations_path) }}
+ {%- elif expression.classname == "ExprAttribute" -%}
+ {%- if annotations_path == "brief" -%}
+ {%- if expression.last.is_enum_value -%}
+ {{ crossref(expression.last.parent, "brief") }}.value
+ {%- else -%}
+ {{ render(expression.last, "brief") }}
+ {%- endif -%}
+ {%- elif annotations_path == "full" -%}
+ {{ render(expression.first, "full") }}
+ {%- for element in expression -%}
+ {%- if not loop.first -%}
+ {{ render(element, "brief") }}
+ {%- endif -%}
+ {%- endfor -%}
+ {%- else -%}
+ {%- for element in expression -%}
+ {{ render(element, annotations_path) }}
+ {%- endfor -%}
+ {%- endif -%}
+ {%- else -%}
+ {%- for element in expression -%}
+ {{ render(element, annotations_path) }}
+ {%- endfor -%}
+ {%- endif -%}
+{%- endmacro -%}
+
+{{ render(expression, config.annotations_path) }}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html b/src/mkdocstrings_handlers/python/templates/material/_base/function.html
index 5c2ac29e..07be5abb 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html
@@ -1,98 +1,11 @@
-{{ log.debug("Rendering " + function.path) }}
-
-{% import "language.html" as lang with context %}
-
-
-{% with obj = function, html_id = function.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 function_name = function.path if show_full_path else function.name %}
- {% set symbol_type = "method" if function.parent.is_class else "function" %}
-
- {% if not root or config.show_root_heading %}
- {% filter heading(
- heading_level,
- role="function",
- id=html_id,
- class="doc doc-heading",
- toc_label=(('
')|safe if config.show_symbol_type_toc else '') + function.name,
- ) %}
-
- {% block heading scoped %}
- {% if config.show_symbol_type_heading %}
{% endif %}
- {% if config.separate_signature %}
-
{{ function_name }}
- {% else %}
- {%+ filter highlight(language="python", inline=True) %}
- {{ function_name }}{% include "signature.html" with context %}
- {% endfilter %}
- {% endif %}
- {% endblock heading %}
-
- {% block labels scoped %}
- {% with labels = function.labels %}
- {% include "labels.html" with context %}
- {% endwith %}
- {% endblock labels %}
-
- {% endfilter %}
-
- {% block signature scoped %}
- {% if config.separate_signature %}
- {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %}
- {{ function.name }}
- {% endfilter %}
- {% endif %}
- {% endblock signature %}
-
- {% else %}
-
- {% if config.show_root_toc_entry %}
- {% filter heading(
- heading_level,
- role="function",
- id=html_id,
- toc_label=(('
')|safe if config.show_symbol_type_toc else '') + function.name,
- hidden=True,
- ) %}
- {% endfilter %}
- {% endif %}
- {% set heading_level = heading_level - 1 %}
- {% endif %}
-
-
- {% block contents scoped %}
- {% block docstring scoped %}
- {% with docstring_sections = function.docstring.parsed %}
- {% include "docstring.html" with context %}
- {% endwith %}
- {% endblock docstring %}
-
- {% block source scoped %}
- {% if config.show_source and function.source %}
-
- {{ lang.t("Source code in") }}
- {%- if function.relative_filepath.is_absolute() -%}
- {{ function.relative_package_filepath }}
- {%- else -%}
- {{ function.relative_filepath }}
- {%- endif -%}
-
- {{ function.source|highlight(language="python", linestart=function.lineno, linenums=True) }}
-
- {% endif %}
- {% endblock source %}
- {% endblock contents %}
-
-
-{% endwith %}
-
+ {% with obj = function, html_id = function.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 function_name = function.path if show_full_path else function.name %}
+ {#- Brief or full function name depending on configuration. -#}
+ {% set symbol_type = "method" if function.parent.is_class else "function" %}
+ {#- Symbol type: method when parent is a class, function otherwise. -#}
+
+ {% if not root or config.show_root_heading %}
+ {% filter heading(
+ heading_level,
+ role="function",
+ id=html_id,
+ class="doc doc-heading",
+ toc_label=(('
')|safe if config.show_symbol_type_toc else '') + function.name,
+ ) %}
+
+ {% block heading scoped %}
+ {#- Heading block.
+
+ This block renders the heading for the function.
+ -#}
+ {% if config.show_symbol_type_heading %}
{% endif %}
+ {% if config.separate_signature %}
+
{{ function_name }}
+ {% else %}
+ {%+ filter highlight(language="python", inline=True) %}
+ {{ function_name }}{% include "signature"|get_template with context %}
+ {% endfilter %}
+ {% endif %}
+ {% endblock heading %}
+
+ {% block labels scoped %}
+ {#- Labels block.
+
+ This block renders the labels for the function.
+ -#}
+ {% with labels = function.labels %}
+ {% include "labels"|get_template with context %}
+ {% endwith %}
+ {% endblock labels %}
+
+ {% endfilter %}
+
+ {% block signature scoped %}
+ {#- Signature block.
+
+ This block renders the signature for the function.
+ -#}
+ {% if config.separate_signature %}
+ {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %}
+ {{ function.name }}
+ {% endfilter %}
+ {% endif %}
+ {% endblock signature %}
+
+ {% else %}
+
+ {% if config.show_root_toc_entry %}
+ {% filter heading(
+ heading_level,
+ role="function",
+ id=html_id,
+ toc_label=(('
')|safe if config.show_symbol_type_toc else '') + function.name,
+ hidden=True,
+ ) %}
+ {% endfilter %}
+ {% endif %}
+ {% set heading_level = heading_level - 1 %}
+ {% endif %}
+
+
+ {% block contents scoped %}
+ {#- Contents block.
+
+ This block renders the contents of the function.
+ 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 function.
+ -#}
+ {% with docstring_sections = function.docstring.parsed %}
+ {% include "docstring"|get_template with context %}
+ {% endwith %}
+ {% endblock docstring %}
+
+ {% block source scoped %}
+ {#- Source block.
+
+ This block renders the source code for the function.
+ -#}
+ {% if config.show_source and function.source %}
+
+ {{ lang.t("Source code in") }}
+ {%- if function.relative_filepath.is_absolute() -%}
+ {{ function.relative_package_filepath }}
+ {%- else -%}
+ {{ function.relative_filepath }}
+ {%- endif -%}
+
+ {{ function.source|highlight(language="python", linestart=function.lineno, linenums=True) }}
+
+ {% endif %}
+ {% endblock source %}
+ {% endblock contents %}
+
+
+ {% endwith %}
+
{{ label }}
- {% endfor %}
-
-{% endif %}
+{% extends "_base/labels.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/labels.html' is deprecated, extend '_base/labels.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja
new file mode 100644
index 00000000..dced4913
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja
@@ -0,0 +1,25 @@
+{#- Template for object labels.
+
+Labels are additional information that can be displayed alongside an object.
+Example labels include "property", "writable" or "cached" for properties,
+"classmethod" or "staticmethod" for methods, etc.
+
+Context:
+ labels (list): The list of labels to render.
+ config (dict): The configuration options.
+-#}
+
+{% if config.show_labels and labels %}
+ {% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering labels") }}
+ {% endblock logs %}
+
+ {% for label in labels|sort %}
+ {{ label }}
+ {% endfor %}
+
+{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/language.html b/src/mkdocstrings_handlers/python/templates/material/_base/language.html
new file mode 100644
index 00000000..c97d0c31
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/language.html
@@ -0,0 +1,11 @@
+{% extends "_base/language.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/language.html' is deprecated, extend '_base/language.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja
new file mode 100644
index 00000000..5b643726
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja
@@ -0,0 +1,18 @@
+{#- Import translation macros for the given language and fallback language. -#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+{% endblock logs %}
+
+{% set lang_pth = "languages/" ~ locale | get_template %}
+{% if lang_pth is existing_template %}
+ {% import lang_pth as lang %}
+ {% import "languages/en"|get_template as fallback %}
+ {% macro t(key) %}{{ lang.t(key) or fallback.t(key) }}{% endmacro %}
+{% else %}
+ {% import "languages/en"|get_template as lang %}
+ {% macro t(key) %}{{ lang.t(key) }}{% endmacro %}
+{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html
index 1f76e059..eab87415 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html
@@ -1,37 +1,11 @@
-
-{% macro t(key) %}{{ {
- "ATTRIBUTE": "ATTRIBUTE",
- "Attributes:": "Attributes:",
- "Classes:": "Classes:",
- "CLASS": "CLASS",
- "DEFAULT:": "DEFAULT:",
- "Default": "Default",
- "default:": "default:",
- "DESCRIPTION": "DESCRIPTION",
- "Description": "Description",
- "Examples:": "Examples:",
- "Functions:": "Functions:",
- "FUNCTION": "FUNCTION",
- "Methods:": "Methods:",
- "METHOD": "METHOD",
- "Modules:": "Modules:",
- "MODULE": "MODULE",
- "Name": "Name",
- "Other Parameters:": "Other Parameters:",
- "PARAMETER": "PARAMETER",
- "Parameters:": "Parameters:",
- "RAISES": "RAISES",
- "Raises:" : "Raises:",
- "RECEIVES": "RECEIVES",
- "Receives:": "Receives:",
- "required": "required",
- "RETURNS": "RETURNS",
- "Returns:": "Returns:",
- "Source code in": "Source code in",
- "TYPE:": "TYPE:",
- "Type": "Type",
- "WARNS": "WARNS",
- "Warns:": "Warns:",
- "YIELDS": "YIELDS",
- "Yields:": "Yields:",
-}[key] }}{% endmacro %}
\ No newline at end of file
+{% extends "_base/languages/en.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/languages/en.html' is deprecated, extend '_base/languages/en.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html.jinja
new file mode 100644
index 00000000..d988b6ab
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html.jinja
@@ -0,0 +1,45 @@
+{#- Macro for English translations. -#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+{% endblock logs %}
+
+{% macro t(key) %}{{ {
+ "ATTRIBUTE": "ATTRIBUTE",
+ "Attributes:": "Attributes:",
+ "Classes:": "Classes:",
+ "CLASS": "CLASS",
+ "DEFAULT:": "DEFAULT:",
+ "Default": "Default",
+ "default:": "default:",
+ "DESCRIPTION": "DESCRIPTION",
+ "Description": "Description",
+ "Examples:": "Examples:",
+ "Functions:": "Functions:",
+ "FUNCTION": "FUNCTION",
+ "Methods:": "Methods:",
+ "METHOD": "METHOD",
+ "Modules:": "Modules:",
+ "MODULE": "MODULE",
+ "Name": "Name",
+ "Other Parameters:": "Other Parameters:",
+ "PARAMETER": "PARAMETER",
+ "Parameters:": "Parameters:",
+ "RAISES": "RAISES",
+ "Raises:" : "Raises:",
+ "RECEIVES": "RECEIVES",
+ "Receives:": "Receives:",
+ "required": "required",
+ "RETURNS": "RETURNS",
+ "Returns:": "Returns:",
+ "Source code in": "Source code in",
+ "TYPE:": "TYPE:",
+ "Type": "Type",
+ "WARNS": "WARNS",
+ "Warns:": "Warns:",
+ "YIELDS": "YIELDS",
+ "Yields:": "Yields:",
+}[key] }}{% endmacro %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html
index 456e1170..14319499 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html
@@ -1,37 +1,11 @@
-
-{% macro t(key) %}{{ {
- "ATTRIBUTE": "属性",
- "Attributes:": "属性：",
- "Classes:": "",
- "CLASS": "",
- "DEFAULT:": "デフォルト：",
- "Default": "デフォルト",
- "default:": "デフォルト：",
- "DESCRIPTION": "デスクリプション",
- "Description": "デスクリプション",
- "Examples:": "例：",
- "Functions:": "",
- "FUNCTION": "",
- "Methods:": "",
- "METHOD": "",
- "Modules:": "",
- "MODULE": "",
- "Name": "名前",
- "Other Parameters:": "他の引数：",
- "PARAMETER": "引数",
- "Parameters:": "引数：",
- "RAISES": "発生",
- "Raises:" : "発生：",
- "RECEIVES": "取得",
- "Receives:": "取得：",
- "required": "必須",
- "RETURNS": "戻り値",
- "Returns:": "戻り値：",
- "Source code in": "ソースコード位置：",
- "TYPE:": "タイプ：",
- "Type": "タイプ",
- "WARNS": "警告",
- "Warns:": "警告：",
- "YIELDS": "返す",
- "Yields:": "返す：",
-}[key] }}{% endmacro %}
\ No newline at end of file
+{% extends "_base/languages/ja.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/languages/ja.html' is deprecated, extend '_base/languages/ja.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja
new file mode 100644
index 00000000..a6b7728b
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja
@@ -0,0 +1,45 @@
+{#- Macro for Japanese translations. -#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+{% endblock logs %}
+
+{% macro t(key) %}{{ {
+ "ATTRIBUTE": "属性",
+ "Attributes:": "属性：",
+ "Classes:": "",
+ "CLASS": "",
+ "DEFAULT:": "デフォルト：",
+ "Default": "デフォルト",
+ "default:": "デフォルト：",
+ "DESCRIPTION": "デスクリプション",
+ "Description": "デスクリプション",
+ "Examples:": "例：",
+ "Functions:": "",
+ "FUNCTION": "",
+ "Methods:": "",
+ "METHOD": "",
+ "Modules:": "",
+ "MODULE": "",
+ "Name": "名前",
+ "Other Parameters:": "他の引数：",
+ "PARAMETER": "引数",
+ "Parameters:": "引数：",
+ "RAISES": "発生",
+ "Raises:" : "発生：",
+ "RECEIVES": "取得",
+ "Receives:": "取得：",
+ "required": "必須",
+ "RETURNS": "戻り値",
+ "Returns:": "戻り値：",
+ "Source code in": "ソースコード位置：",
+ "TYPE:": "タイプ：",
+ "Type": "タイプ",
+ "WARNS": "警告",
+ "Warns:": "警告：",
+ "YIELDS": "返す",
+ "Yields:": "返す：",
+}[key] }}{% endmacro %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html
index 9c018f27..0b281195 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html
@@ -1,37 +1,11 @@
-
-{% macro t(key) %}{{ {
- "ATTRIBUTE": "属性",
- "Attributes:": "属性：",
- "Classes:": "",
- "CLASS": "",
- "DEFAULT:": "默认：",
- "Default": "默认",
- "default:": "默认：",
- "DESCRIPTION": "描述",
- "Description": "描述",
- "Examples:": "示例：",
- "Functions:": "",
- "FUNCTION": "",
- "Methods:": "",
- "METHOD": "",
- "Modules:": "",
- "MODULE": "",
- "Name": "名称",
- "Other Parameters:": "其他参数：",
- "PARAMETER": "参数",
- "Parameters:": "参数：",
- "RAISES": "引发",
- "Raises:" : "引发：",
- "Receives:": "接收：",
- "RECEIVES": "接收",
- "required": "必需",
- "RETURNS": "返回",
- "Returns:": "返回：",
- "Source code in": "源代码位于：",
- "TYPE:": "类型：",
- "Type": "类型",
- "Warns:": "警告：",
- "WARNS": "警告",
- "YIELDS": "产生",
- "Yields:": "产生：",
-}[key] }}{% endmacro %}
\ No newline at end of file
+{% extends "_base/languages/zh.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/languages/zh.html' is deprecated, extend '_base/languages/zh.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja
new file mode 100644
index 00000000..f748b83c
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja
@@ -0,0 +1,45 @@
+{#- Macro for Chinese translations. -#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+{% endblock logs %}
+
+{% macro t(key) %}{{ {
+ "ATTRIBUTE": "属性",
+ "Attributes:": "属性：",
+ "Classes:": "",
+ "CLASS": "",
+ "DEFAULT:": "默认：",
+ "Default": "默认",
+ "default:": "默认：",
+ "DESCRIPTION": "描述",
+ "Description": "描述",
+ "Examples:": "示例：",
+ "Functions:": "",
+ "FUNCTION": "",
+ "Methods:": "",
+ "METHOD": "",
+ "Modules:": "",
+ "MODULE": "",
+ "Name": "名称",
+ "Other Parameters:": "其他参数：",
+ "PARAMETER": "参数",
+ "Parameters:": "参数：",
+ "RAISES": "引发",
+ "Raises:" : "引发：",
+ "Receives:": "接收：",
+ "RECEIVES": "接收",
+ "required": "必需",
+ "RETURNS": "返回",
+ "Returns:": "返回：",
+ "Source code in": "源代码位于：",
+ "TYPE:": "类型：",
+ "Type": "类型",
+ "Warns:": "警告：",
+ "WARNS": "警告",
+ "YIELDS": "产生",
+ "Yields:": "产生：",
+}[key] }}{% endmacro %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/module.html b/src/mkdocstrings_handlers/python/templates/material/_base/module.html
index 7d45e321..918ab6d0 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/module.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/module.html
@@ -1,74 +1,11 @@
-{{ log.debug("Rendering " + module.path) }}
-
-
-{% with obj = module, html_id = module.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 module_name = module.path if show_full_path else module.name %}
-
- {% if not root or config.show_root_heading %}
- {% filter heading(
- heading_level,
- role="module",
- id=html_id,
- class="doc doc-heading",
- toc_label=('
'|safe if config.show_symbol_type_toc else '') + module.name,
- ) %}
-
- {% block heading scoped %}
- {% if config.show_symbol_type_heading %}
{% endif %}
- {% if config.separate_signature %}
-
{{ module_name }}
- {% else %}
-
{{ module_name }}
- {% endif %}
- {% endblock heading %}
-
- {% block labels scoped %}
- {% with labels = module.labels %}
- {% include "labels.html" with context %}
- {% endwith %}
- {% endblock labels %}
-
- {% endfilter %}
-
- {% else %}
- {% if config.show_root_toc_entry %}
- {% filter heading(heading_level,
- role="module",
- id=html_id,
- toc_label=('
'|safe if config.show_symbol_type_toc else '') + module.name,
- hidden=True,
- ) %}
- {% endfilter %}
- {% endif %}
- {% set heading_level = heading_level - 1 %}
- {% endif %}
-
-
- {% block contents scoped %}
- {% block docstring scoped %}
- {% with docstring_sections = module.docstring.parsed %}
- {% include "docstring.html" with context %}
- {% endwith %}
- {% endblock docstring %}
-
- {% block children scoped %}
- {% set root = False %}
- {% set heading_level = heading_level + 1 %}
- {% include "children.html" with context %}
- {% endblock children %}
- {% endblock contents %}
-
-
-{% endwith %}
-
+ {% with obj = module, html_id = module.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 module_name = module.path if show_full_path else module.name %}
+
+ {% if not root or config.show_root_heading %}
+ {% filter heading(
+ heading_level,
+ role="module",
+ id=html_id,
+ class="doc doc-heading",
+ toc_label=('
'|safe if config.show_symbol_type_toc else '') + module.name,
+ ) %}
+
+ {% block heading scoped %}
+ {#- Heading block.
+
+ This block renders the heading for the module.
+ -#}
+ {% if config.show_symbol_type_heading %}
{% endif %}
+ {% if config.separate_signature %}
+
{{ module_name }}
+ {% else %}
+
{{ module_name }}
+ {% endif %}
+ {% endblock heading %}
+
+ {% block labels scoped %}
+ {#- Labels block.
+
+ This block renders the labels for the module.
+ -#}
+ {% with labels = module.labels %}
+ {% include "labels"|get_template with context %}
+ {% endwith %}
+ {% endblock labels %}
+
+ {% endfilter %}
+
+ {% else %}
+ {% if config.show_root_toc_entry %}
+ {% filter heading(heading_level,
+ role="module",
+ id=html_id,
+ toc_label=('
'|safe if config.show_symbol_type_toc else '') + module.name,
+ hidden=True,
+ ) %}
+ {% endfilter %}
+ {% endif %}
+ {% set heading_level = heading_level - 1 %}
+ {% endif %}
+
+
+ {% block contents scoped %}
+ {#- Contents block.
+
+ This block renders the contents of the module.
+ 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 module.
+ -#}
+ {% with docstring_sections = module.docstring.parsed %}
+ {% include "docstring"|get_template with context %}
+ {% endwith %}
+ {% endblock docstring %}
+
+ {% block children scoped %}
+ {#- Children block.
+
+ This block renders the children (members) of the module.
+ -#}
+ {% set root = False %}
+ {% set heading_level = heading_level + 1 %}
+ {% include "children"|get_template with context %}
+ {% endblock children %}
+ {% endblock contents %}
+
+
+ {% endwith %}
+
+
+
+
+
+
+
+ | {{ section.title or lang.t("Attributes:") }} |
+
+
+ |
+
+
+
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html
new file mode 100644
index 00000000..eae60aa7
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html
@@ -0,0 +1,11 @@
+{% extends "_base/docstring/other_parameters.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/other_parameters.html' is deprecated, extend '_base/docstring/other_parameters.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html.jinja
new file mode 100644
index 00000000..4b416b65
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html.jinja
@@ -0,0 +1,49 @@
+{#- Template for "Other parameters" sections in docstrings.
+
+This template renders a list of documented other parameters in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug() }}
+{% endblock %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+
+
+
+
+
+
+
+ | {{ section.title or lang.t("Other parameters:") }} |
+
+
+ |
+
+
+
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html
new file mode 100644
index 00000000..f5745464
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html
@@ -0,0 +1,11 @@
+{% extends "_base/docstring/parameters.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/parameters.html' is deprecated, extend '_base/docstring/parameters.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja
new file mode 100644
index 00000000..10bbd7ba
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja
@@ -0,0 +1,54 @@
+{#- Template for "Parameters" sections in docstrings.
+
+This template renders a list of documented parameters in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug() }}
+{% endblock %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+
+
+
+
+
+
+
+ | {{ section.title or lang.t("Parameters:") }} |
+
+
+ |
+
+
+
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html
new file mode 100644
index 00000000..361b9732
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html
@@ -0,0 +1,11 @@
+{% extends "_base/docstring/raises.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/raises.html' is deprecated, extend '_base/docstring/raises.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja
new file mode 100644
index 00000000..f350bc97
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja
@@ -0,0 +1,48 @@
+{#- Template for "Raises" sections in docstrings.
+
+This template renders a list of documented exceptions in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug() }}
+{% endblock %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+
+
+
+
+
+
+
+ | {{ section.title or lang.t("Raises:") }} |
+
+
+ |
+
+
+
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html
new file mode 100644
index 00000000..e5a115c1
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html
@@ -0,0 +1,11 @@
+{% extends "_base/docstring/receives.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/receives.html' is deprecated, extend '_base/docstring/receives.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja
new file mode 100644
index 00000000..804a04a0
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja
@@ -0,0 +1,51 @@
+{#- Template for "Receives" sections in docstrings.
+
+This template renders a list of documented received values (generators) in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug() }}
+{% endblock %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+
+
+
+
+
+
+
+ | {{ section.title or lang.t("Receives:") }} |
+
+
+ |
+
+
+
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html
new file mode 100644
index 00000000..0e7807ac
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html
@@ -0,0 +1,11 @@
+{% extends "_base/docstring/returns.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/returns.html' is deprecated, extend '_base/docstring/returns.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja
new file mode 100644
index 00000000..0074327a
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja
@@ -0,0 +1,51 @@
+{#- Template for "Returns" sections in docstrings.
+
+This template renders a list of documented returned values in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug() }}
+{% endblock %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+
+
+
+
+
+
+
+ | {{ section.title or lang.t("Returns:") }} |
+
+
+ |
+
+
+
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html
new file mode 100644
index 00000000..b7b937a9
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html
@@ -0,0 +1,11 @@
+{% extends "_base/docstring/warns.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/warns.html' is deprecated, extend '_base/docstring/warns.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja
new file mode 100644
index 00000000..88308b68
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja
@@ -0,0 +1,48 @@
+{#- Template for "Warns" sections in docstrings.
+
+This template renders a list of documented warnings in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug() }}
+{% endblock %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+
+
+
+
+
+
+
+ | {{ section.title or lang.t("Warns:") }} |
+
+
+ |
+
+
+
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html
new file mode 100644
index 00000000..ecd6f513
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html
@@ -0,0 +1,11 @@
+{% extends "_base/docstring/yields.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/docstring/yields.html' is deprecated, extend '_base/docstring/yields.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja
new file mode 100644
index 00000000..bd43955d
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja
@@ -0,0 +1,51 @@
+{#- Template for "Yields" sections in docstrings.
+
+This template renders a list of documented yielded values (generators) in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug() }}
+{% endblock %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+
+
+
+
+
+
+
+ | {{ section.title or lang.t("Yields:") }} |
+
+
+ |
+
+
+
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html
new file mode 100644
index 00000000..c97d0c31
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html
@@ -0,0 +1,11 @@
+{% extends "_base/language.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/language.html' is deprecated, extend '_base/language.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html.jinja
new file mode 100644
index 00000000..5b643726
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html.jinja
@@ -0,0 +1,18 @@
+{#- Import translation macros for the given language and fallback language. -#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+{% endblock logs %}
+
+{% set lang_pth = "languages/" ~ locale | get_template %}
+{% if lang_pth is existing_template %}
+ {% import lang_pth as lang %}
+ {% import "languages/en"|get_template as fallback %}
+ {% macro t(key) %}{{ lang.t(key) or fallback.t(key) }}{% endmacro %}
+{% else %}
+ {% import "languages/en"|get_template as lang %}
+ {% macro t(key) %}{{ lang.t(key) }}{% endmacro %}
+{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/en.html b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/en.html
new file mode 100644
index 00000000..eab87415
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/en.html
@@ -0,0 +1,11 @@
+{% extends "_base/languages/en.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/languages/en.html' is deprecated, extend '_base/languages/en.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/en.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/en.html.jinja
new file mode 100644
index 00000000..5a771d30
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/en.html.jinja
@@ -0,0 +1,39 @@
+
+{% block logs scoped %}
+{% endblock logs %}
+{% macro t(key) %}{{ {
+ "ATTRIBUTE": "ATTRIBUTE",
+ "Attributes:": "Attributes:",
+ "Classes:": "Classes:",
+ "CLASS": "CLASS",
+ "DEFAULT:": "DEFAULT:",
+ "Default": "Default",
+ "default:": "default:",
+ "DESCRIPTION": "DESCRIPTION",
+ "Description": "Description",
+ "Examples:": "Examples:",
+ "Functions:": "Functions:",
+ "FUNCTION": "FUNCTION",
+ "Methods:": "Methods:",
+ "METHOD": "METHOD",
+ "Modules:": "Modules:",
+ "MODULE": "MODULE",
+ "Name": "Name",
+ "Other Parameters:": "Other Parameters:",
+ "PARAMETER": "PARAMETER",
+ "Parameters:": "Parameters:",
+ "RAISES": "RAISES",
+ "Raises:" : "Raises:",
+ "RECEIVES": "RECEIVES",
+ "Receives:": "Receives:",
+ "required": "required",
+ "RETURNS": "RETURNS",
+ "Returns:": "Returns:",
+ "Source code in": "Source code in",
+ "TYPE:": "TYPE:",
+ "Type": "Type",
+ "WARNS": "WARNS",
+ "Warns:": "Warns:",
+ "YIELDS": "YIELDS",
+ "Yields:": "Yields:",
+}[key] }}{% endmacro %}
\ No newline at end of file
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/ja.html b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/ja.html
new file mode 100644
index 00000000..14319499
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/ja.html
@@ -0,0 +1,11 @@
+{% extends "_base/languages/ja.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/languages/ja.html' is deprecated, extend '_base/languages/ja.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/ja.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/ja.html.jinja
new file mode 100644
index 00000000..748fd8b7
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/ja.html.jinja
@@ -0,0 +1,39 @@
+
+{% block logs scoped %}
+{% endblock logs %}
+{% macro t(key) %}{{ {
+ "ATTRIBUTE": "属性",
+ "Attributes:": "属性：",
+ "Classes:": "",
+ "CLASS": "",
+ "DEFAULT:": "デフォルト：",
+ "Default": "デフォルト",
+ "default:": "デフォルト：",
+ "DESCRIPTION": "デスクリプション",
+ "Description": "デスクリプション",
+ "Examples:": "例：",
+ "Functions:": "",
+ "FUNCTION": "",
+ "Methods:": "",
+ "METHOD": "",
+ "Modules:": "",
+ "MODULE": "",
+ "Name": "名前",
+ "Other Parameters:": "他の引数：",
+ "PARAMETER": "引数",
+ "Parameters:": "引数：",
+ "RAISES": "発生",
+ "Raises:" : "発生：",
+ "RECEIVES": "取得",
+ "Receives:": "取得：",
+ "required": "必須",
+ "RETURNS": "戻り値",
+ "Returns:": "戻り値：",
+ "Source code in": "ソースコード位置：",
+ "TYPE:": "タイプ：",
+ "Type": "タイプ",
+ "WARNS": "警告",
+ "Warns:": "警告：",
+ "YIELDS": "返す",
+ "Yields:": "返す：",
+}[key] }}{% endmacro %}
\ No newline at end of file
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/zh.html b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/zh.html
new file mode 100644
index 00000000..0b281195
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/zh.html
@@ -0,0 +1,11 @@
+{% extends "_base/languages/zh.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/languages/zh.html' is deprecated, extend '_base/languages/zh.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/zh.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/zh.html.jinja
new file mode 100644
index 00000000..772e33cd
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/zh.html.jinja
@@ -0,0 +1,39 @@
+
+{% block logs scoped %}
+{% endblock logs %}
+{% macro t(key) %}{{ {
+ "ATTRIBUTE": "属性",
+ "Attributes:": "属性：",
+ "Classes:": "",
+ "CLASS": "",
+ "DEFAULT:": "默认：",
+ "Default": "默认",
+ "default:": "默认：",
+ "DESCRIPTION": "描述",
+ "Description": "描述",
+ "Examples:": "示例：",
+ "Functions:": "",
+ "FUNCTION": "",
+ "Methods:": "",
+ "METHOD": "",
+ "Modules:": "",
+ "MODULE": "",
+ "Name": "名称",
+ "Other Parameters:": "其他参数：",
+ "PARAMETER": "参数",
+ "Parameters:": "参数：",
+ "RAISES": "引发",
+ "Raises:" : "引发：",
+ "Receives:": "接收：",
+ "RECEIVES": "接收",
+ "required": "必需",
+ "RETURNS": "返回",
+ "Returns:": "返回：",
+ "Source code in": "源代码位于：",
+ "TYPE:": "类型：",
+ "Type": "类型",
+ "Warns:": "警告：",
+ "WARNS": "警告",
+ "YIELDS": "产生",
+ "Yields:": "产生：",
+}[key] }}{% endmacro %}
\ No newline at end of file
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/attributes.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/attributes.html
index 8411dda6..4ac364b0 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/attributes.html
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/attributes.html
@@ -1,33 +1 @@
-{{ log.debug() }}
-
-{% import "language.html" as lang with context %}
-
-
-
-
-
-
-
-
- | {{ section.title or lang.t("Attributes:") }} |
-
-
- |
-
-
-
+{% extends "_base/docstring/attributes.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/attributes.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/attributes.html.jinja
new file mode 100644
index 00000000..4ac364b0
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/attributes.html.jinja
@@ -0,0 +1 @@
+{% extends "_base/docstring/attributes.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/other_parameters.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/other_parameters.html
index 44963a5a..7c50379b 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/other_parameters.html
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/other_parameters.html
@@ -1,33 +1 @@
-{{ log.debug() }}
-
-{% import "language.html" as lang with context %}
-
-
-
-
-
-
-
-
- | {{ section.title or lang.t("Other parameters:") }} |
-
-
- |
-
-
-
+{% extends "_base/docstring/other_parameters.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/other_parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/other_parameters.html.jinja
new file mode 100644
index 00000000..7c50379b
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/other_parameters.html.jinja
@@ -0,0 +1 @@
+{% extends "_base/docstring/other_parameters.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/parameters.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/parameters.html
index e062b835..70c557fb 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/parameters.html
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/parameters.html
@@ -1,38 +1 @@
-{{ log.debug() }}
-
-{% import "language.html" as lang with context %}
-
-
-
-
-
-
-
-
- | {{ section.title or lang.t("Parameters:") }} |
-
-
- |
-
-
-
+{% extends "_base/docstring/parameters.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/parameters.html.jinja
new file mode 100644
index 00000000..70c557fb
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/parameters.html.jinja
@@ -0,0 +1 @@
+{% extends "_base/docstring/parameters.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/raises.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/raises.html
index f82437dd..f8c3cf03 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/raises.html
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/raises.html
@@ -1,32 +1 @@
-{{ log.debug() }}
-
-{% import "language.html" as lang with context %}
-
-
-
-
-
-
-
-
- | {{ section.title or lang.t("Raises:") }} |
-
-
- |
-
-
-
+{% extends "_base/docstring/raises.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/raises.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/raises.html.jinja
new file mode 100644
index 00000000..f8c3cf03
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/raises.html.jinja
@@ -0,0 +1 @@
+{% extends "_base/docstring/raises.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/receives.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/receives.html
index 2ab1c2fd..004ff00e 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/receives.html
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/receives.html
@@ -1,35 +1 @@
-{{ log.debug() }}
-
-{% import "language.html" as lang with context %}
-
-
-
-
-
-
-
-
- | {{ section.title or lang.t("Receives:") }} |
-
-
- |
-
-
-
+{% extends "_base/docstring/receives.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/receives.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/receives.html.jinja
new file mode 100644
index 00000000..004ff00e
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/receives.html.jinja
@@ -0,0 +1 @@
+{% extends "_base/docstring/receives.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/returns.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/returns.html
index c2300318..979ce9ef 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/returns.html
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/returns.html
@@ -1,35 +1 @@
-{{ log.debug() }}
-
-{% import "language.html" as lang with context %}
-
-
-
-
-
-
-
-
- | {{ section.title or lang.t("Returns:") }} |
-
-
- |
-
-
-
+{% extends "_base/docstring/returns.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/returns.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/returns.html.jinja
new file mode 100644
index 00000000..979ce9ef
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/returns.html.jinja
@@ -0,0 +1 @@
+{% extends "_base/docstring/returns.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/warns.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/warns.html
index 35aff0b1..bb06cc85 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/warns.html
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/warns.html
@@ -1,32 +1 @@
-{{ log.debug() }}
-
-{% import "language.html" as lang with context %}
-
-
-
-
-
-
-
-
- | {{ section.title or lang.t("Warns:") }} |
-
-
- |
-
-
-
+{% extends "_base/docstring/warns.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/warns.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/warns.html.jinja
new file mode 100644
index 00000000..bb06cc85
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/warns.html.jinja
@@ -0,0 +1 @@
+{% extends "_base/docstring/warns.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/yields.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/yields.html
index 4d639a75..717ef5d4 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/yields.html
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/yields.html
@@ -1,35 +1 @@
-{{ log.debug() }}
-
-{% import "language.html" as lang with context %}
-
-
-
-
-
-
-
-
- | {{ section.title or lang.t("Yields:") }} |
-
-
- |
-
-
-
+{% extends "_base/docstring/yields.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/yields.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/yields.html.jinja
new file mode 100644
index 00000000..717ef5d4
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/yields.html.jinja
@@ -0,0 +1 @@
+{% extends "_base/docstring/yields.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/language.html b/src/mkdocstrings_handlers/python/templates/readthedocs/language.html
index 26647ff3..b905cff4 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/language.html
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/language.html
@@ -1,10 +1 @@
-
-{% set lang_pth = "languages/" ~ locale ~ ".html" %}
-{% if lang_pth is existing_template %}
- {% import lang_pth as lang %}
- {% import "languages/en.html" as fallback %}
- {% macro t(key) %}{{ lang.t(key) or fallback.t(key) }}{% endmacro %}
-{% else %}
- {% import "languages/en.html" as lang %}
- {% macro t(key) %}{{ lang.t(key) }}{% endmacro %}
-{% endif %}
+{% extends "_base/language.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/language.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/language.html.jinja
new file mode 100644
index 00000000..b905cff4
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/language.html.jinja
@@ -0,0 +1 @@
+{% extends "_base/language.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/languages/en.html b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/en.html
index 1f76e059..931967c1 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/languages/en.html
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/en.html
@@ -1,37 +1 @@
-
-{% macro t(key) %}{{ {
- "ATTRIBUTE": "ATTRIBUTE",
- "Attributes:": "Attributes:",
- "Classes:": "Classes:",
- "CLASS": "CLASS",
- "DEFAULT:": "DEFAULT:",
- "Default": "Default",
- "default:": "default:",
- "DESCRIPTION": "DESCRIPTION",
- "Description": "Description",
- "Examples:": "Examples:",
- "Functions:": "Functions:",
- "FUNCTION": "FUNCTION",
- "Methods:": "Methods:",
- "METHOD": "METHOD",
- "Modules:": "Modules:",
- "MODULE": "MODULE",
- "Name": "Name",
- "Other Parameters:": "Other Parameters:",
- "PARAMETER": "PARAMETER",
- "Parameters:": "Parameters:",
- "RAISES": "RAISES",
- "Raises:" : "Raises:",
- "RECEIVES": "RECEIVES",
- "Receives:": "Receives:",
- "required": "required",
- "RETURNS": "RETURNS",
- "Returns:": "Returns:",
- "Source code in": "Source code in",
- "TYPE:": "TYPE:",
- "Type": "Type",
- "WARNS": "WARNS",
- "Warns:": "Warns:",
- "YIELDS": "YIELDS",
- "Yields:": "Yields:",
-}[key] }}{% endmacro %}
\ No newline at end of file
+{% extends "_base/languages/en.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/languages/en.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/en.html.jinja
new file mode 100644
index 00000000..931967c1
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/en.html.jinja
@@ -0,0 +1 @@
+{% extends "_base/languages/en.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/languages/ja.html b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/ja.html
index 456e1170..17070edf 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/languages/ja.html
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/ja.html
@@ -1,37 +1 @@
-
-{% macro t(key) %}{{ {
- "ATTRIBUTE": "属性",
- "Attributes:": "属性：",
- "Classes:": "",
- "CLASS": "",
- "DEFAULT:": "デフォルト：",
- "Default": "デフォルト",
- "default:": "デフォルト：",
- "DESCRIPTION": "デスクリプション",
- "Description": "デスクリプション",
- "Examples:": "例：",
- "Functions:": "",
- "FUNCTION": "",
- "Methods:": "",
- "METHOD": "",
- "Modules:": "",
- "MODULE": "",
- "Name": "名前",
- "Other Parameters:": "他の引数：",
- "PARAMETER": "引数",
- "Parameters:": "引数：",
- "RAISES": "発生",
- "Raises:" : "発生：",
- "RECEIVES": "取得",
- "Receives:": "取得：",
- "required": "必須",
- "RETURNS": "戻り値",
- "Returns:": "戻り値：",
- "Source code in": "ソースコード位置：",
- "TYPE:": "タイプ：",
- "Type": "タイプ",
- "WARNS": "警告",
- "Warns:": "警告：",
- "YIELDS": "返す",
- "Yields:": "返す：",
-}[key] }}{% endmacro %}
\ No newline at end of file
+{% extends "_base/languages/ja.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/languages/ja.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/ja.html.jinja
new file mode 100644
index 00000000..17070edf
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/ja.html.jinja
@@ -0,0 +1 @@
+{% extends "_base/languages/ja.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html
index 9c018f27..e4ea3116 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html
@@ -1,37 +1 @@
-
-{% macro t(key) %}{{ {
- "ATTRIBUTE": "属性",
- "Attributes:": "属性：",
- "Classes:": "",
- "CLASS": "",
- "DEFAULT:": "默认：",
- "Default": "默认",
- "default:": "默认：",
- "DESCRIPTION": "描述",
- "Description": "描述",
- "Examples:": "示例：",
- "Functions:": "",
- "FUNCTION": "",
- "Methods:": "",
- "METHOD": "",
- "Modules:": "",
- "MODULE": "",
- "Name": "名称",
- "Other Parameters:": "其他参数：",
- "PARAMETER": "参数",
- "Parameters:": "参数：",
- "RAISES": "引发",
- "Raises:" : "引发：",
- "Receives:": "接收：",
- "RECEIVES": "接收",
- "required": "必需",
- "RETURNS": "返回",
- "Returns:": "返回：",
- "Source code in": "源代码位于：",
- "TYPE:": "类型：",
- "Type": "类型",
- "Warns:": "警告：",
- "WARNS": "警告",
- "YIELDS": "产生",
- "Yields:": "产生：",
-}[key] }}{% endmacro %}
\ No newline at end of file
+{% extends "_base/languages/zh.html.jinja" %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html.jinja
new file mode 100644
index 00000000..e4ea3116
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html.jinja
@@ -0,0 +1 @@
+{% extends "_base/languages/zh.html.jinja" %}
diff --git a/tests/conftest.py b/tests/conftest.py
index f7b28105..ab2a145a 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -93,4 +93,4 @@ def fixture_handler(plugin: MkdocstringsPlugin, ext_markdown: Markdown) -> Pytho
"""
handler = plugin.handlers.get_handler("python")
handler._update_env(ext_markdown, plugin.handlers._config)
- return handler # type: ignore[return-value]
+ return handler
diff --git a/tests/test_handler.py b/tests/test_handler.py
index e1d92c18..9f833d12 100644
--- a/tests/test_handler.py
+++ b/tests/test_handler.py
@@ -62,7 +62,7 @@ def test_render_docstring_examples_section(handler: PythonHandler) -> None:
(DocstringSectionKind.examples, ">>> print('Hello')\nHello"),
],
)
- template = handler.env.get_template("docstring/examples.html")
+ template = handler.env.get_template("docstring/examples.html.jinja")
rendered = template.render(section=section, locale="en")
template.render(section=section, locale="not_existing")
assert "This is an example.
" in rendered