From 583b8fefd987ccaa37a016121427e1141827ff71 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= <dev@pawamoy.fr>
Date: Mon, 29 Apr 2024 12:00:49 +0200
Subject: [PATCH] docs: Document Jinja templates

Issue-149: https://github.com/mkdocstrings/python/issues/149
PR-156: https://github.com/mkdocstrings/python/pull/156
---
 .../material/_base/attribute.html.jinja       | 38 ++++++++++++++
 .../material/_base/children.html.jinja        | 16 ++++++
 .../templates/material/_base/class.html.jinja | 50 ++++++++++++++++++-
 .../material/_base/docstring.html.jinja       | 17 +++++++
 .../_base/docstring/admonition.html.jinja     | 15 +++++-
 .../_base/docstring/attributes.html.jinja     | 17 +++++++
 .../_base/docstring/classes.html.jinja        | 17 +++++++
 .../_base/docstring/examples.html.jinja       | 14 ++++++
 .../_base/docstring/functions.html.jinja      | 17 +++++++
 .../_base/docstring/modules.html.jinja        | 17 +++++++
 .../docstring/other_parameters.html.jinja     | 17 +++++++
 .../_base/docstring/parameters.html.jinja     | 17 +++++++
 .../_base/docstring/raises.html.jinja         | 17 +++++++
 .../_base/docstring/receives.html.jinja       | 17 +++++++
 .../_base/docstring/returns.html.jinja        | 17 +++++++
 .../material/_base/docstring/warns.html.jinja | 17 +++++++
 .../_base/docstring/yields.html.jinja         | 17 +++++++
 .../material/_base/expression.html.jinja      | 30 +++++++++++
 .../material/_base/function.html.jinja        | 44 ++++++++++++++++
 .../material/_base/labels.html.jinja          | 15 ++++++
 .../material/_base/language.html.jinja        |  8 ++-
 .../material/_base/languages/en.html.jinja    | 10 +++-
 .../material/_base/languages/ja.html.jinja    | 10 +++-
 .../material/_base/languages/zh.html.jinja    | 10 +++-
 .../material/_base/module.html.jinja          | 37 ++++++++++++++
 .../material/_base/signature.html.jinja       | 26 +++++++++-
 .../material/_base/summary.html.jinja         |  6 +++
 .../_base/summary/attributes.html.jinja       |  6 +++
 .../material/_base/summary/classes.html.jinja |  6 +++
 .../_base/summary/functions.html.jinja        |  6 +++
 .../material/_base/summary/modules.html.jinja |  6 +++
 .../_base/docstring/attributes.html.jinja     | 14 ++++++
 .../docstring/other_parameters.html.jinja     | 14 ++++++
 .../_base/docstring/parameters.html.jinja     | 14 ++++++
 .../_base/docstring/raises.html.jinja         | 14 ++++++
 .../_base/docstring/receives.html.jinja       | 14 ++++++
 .../_base/docstring/returns.html.jinja        | 14 ++++++
 .../_base/docstring/warns.html.jinja          | 14 ++++++
 .../_base/docstring/yields.html.jinja         | 14 ++++++
 .../readthedocs/_base/language.html.jinja     | 10 +++-
 40 files changed, 666 insertions(+), 13 deletions(-)

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja
index fd537034..11bc4e77 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja
@@ -1,4 +1,20 @@
+{#- Template for Python attributes.
+
+This template renders a Python attribute (or variable).
+This can be a module attribute or a class attribute.
+
+Context:
+  attribute (griffe.dataclasses.Attribute): The attribute to render.
+  root (bool): Whether this is the root object, injected with `:::` in a Markdown page.
+  heading_level (int): The HTML heading level to use.
+  config (dict): The configuration options.
+-#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
   {{ log.debug("Rendering " + attribute.path) }}
 {% endblock logs %}
 
@@ -27,6 +43,10 @@
         ) %}
 
         {% block heading scoped %}
+          {#- Heading block.
+          
+          This block renders the heading for the attribute.
+          -#}
           {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>{% endif %}
           {% if config.separate_signature %}
             <span class="doc doc-object-name doc-attribute-name">{{ attribute_name }}</span>
@@ -39,6 +59,10 @@
         {% 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 %}
@@ -47,6 +71,10 @@
       {% 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 }}
@@ -70,7 +98,17 @@
 
     <div class="doc doc-contents {% if root %}first{% endif %}">
       {% block contents scoped %}
+        {#- Contents block.
+        
+        This block renders the contents of the attribute.
+        It contains other blocks that users can override.
+        Overriding the contents block allows to rearrange the order of the blocks.
+        -#}
         {% block docstring scoped %}
+          {#- Docstring block.
+          
+          This block renders the docstring for the attribute.
+          -#}
           {% with docstring_sections = attribute.docstring.parsed %}
             {% include "docstring"|get_template with context %}
           {% endwith %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja
index b63b9a6a..b0ec4007 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja
@@ -1,5 +1,21 @@
+{#- 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 %}
 
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja
index 2bfa2bf0..bb32a91c 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja
@@ -1,4 +1,19 @@
+{#- Template for Python classes.
+
+This template renders a Python class.
+
+Context:
+  class (griffe.dataclasses.Class): The class to render.
+  root (bool): Whether this is the root object, injected with `:::` in a Markdown page.
+  heading_level (int): The HTML heading level to use.
+  config (dict): The configuration options.
+-#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
   {{ log.debug("Rendering " + class.path) }}
 {% endblock logs %}
 
@@ -27,6 +42,10 @@
         ) %}
 
         {% block heading scoped %}
+          {#- Heading block.
+          
+          This block renders the heading for the class.
+          -#}
           {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>{% endif %}
           {% if config.separate_signature %}
             <span class="doc doc-object-name doc-class-name">{{ class_name }}</span>
@@ -42,6 +61,10 @@
         {% 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 %}
@@ -50,6 +73,10 @@
       {% 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__"] %}
@@ -76,7 +103,17 @@
 
     <div class="doc doc-contents {% if root %}first{% 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 %}
             <p class="doc doc-class-bases">
               Bases: {% for expression in class.bases -%}
@@ -87,6 +124,10 @@
         {% 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 %}
@@ -100,6 +141,10 @@
         {% 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 %}
@@ -132,6 +177,10 @@
         {% 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 %}
@@ -140,5 +189,4 @@
     </div>
 
   {% endwith %}
-
 </div>
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja
index 8477dc0a..f5095eb4 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja
@@ -1,5 +1,22 @@
+{#- Template for docstrings.
+
+This template renders Python docstrings.
+Griffe parses docstrings into a list of sections, each with a `kind` and a `value`.
+This template can then iterate on these sections and render them according to the configuration.
+
+Context:
+  docstring_sections (list[griffe.docstrings.dataclasses.DocstringSection]): The list of docstring sections.
+  config (dict): The configuration dictionary.
+  heading_level (int): The heading level to use for Markdown conversion.
+  html_id (str): The HTML ID to use for Markdown conversion.
+-#}
+
 {% if docstring_sections %}
   {% block logs scoped %}
+    {#- Logging block.
+    
+    This block can be used to log debug messages, deprecation messages, warnings, etc.
+    -#}
     {{ log.debug("Rendering docstring") }}
   {% endblock logs %}
   {% for section in docstring_sections %}
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
index b5053342..e3400280 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html.jinja
@@ -1,7 +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 %}
+
 <details class="{{ section.value.kind }}" open>
   <summary>{{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True) }}</summary>
   {{ section.value.contents|convert_markdown(heading_level, html_id) }}
-</details>
\ No newline at end of file
+</details>
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
index d1bb3bb0..e6c03dee 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja
@@ -1,11 +1,26 @@
+{#- 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. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Attributes:") }}</span></p>
     <table>
       <thead>
@@ -38,6 +53,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style scoped %}
+    {#- Block for the `list` section style. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Attributes:") }}</span></p>
     <ul>
       {% for attribute in section.value %}
@@ -58,6 +74,7 @@
   {% endblock list_style %}
 {% elif config.docstring_section_style == "spacy" %}
   {% block spacy_style scoped %}
+    {#- Block for the `spacy` section style. -#}
     <table>
       <thead>
         <tr>
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
index 60ec7e54..1aee5fd2 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja
@@ -1,11 +1,26 @@
+{#- 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. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Classes:") }}</span></p>
     <table>
       <thead>
@@ -30,6 +45,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style scoped %}
+    {#- Block for the `list` section style. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Classes:") }}</span></p>
     <ul>
       {% for class in section.value %}
@@ -45,6 +61,7 @@
   {% endblock list_style %}
 {% elif config.docstring_section_style == "spacy" %}
   {% block spacy_style scoped %}
+    {#- Block for the `spacy` section style. -#}
     <table>
       <thead>
         <tr>
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
index 1e79a53a..48913f80 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja
@@ -1,8 +1,22 @@
+{#- 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. -#}
 
 <p><span class="doc-section-title">{{ section.title or lang.t("Examples:") }}</span></p>
 {% for section_type, sub_section in section.value %}
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
index 35197c80..53bda233 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja
@@ -1,11 +1,26 @@
+{#- 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. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Methods:") if obj.is_class else lang.t("Functions:") }}</span></p>
     <table>
       <thead>
@@ -32,6 +47,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style scoped %}
+    {#- Block for the `list` section style. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Methods:") if obj.is_class else lang.t("Functions:") }}</span></p>
     <ul>
       {% for function in section.value %}
@@ -49,6 +65,7 @@
   {% endblock list_style %}
 {% elif config.docstring_section_style == "spacy" %}
   {% block spacy_style scoped %}
+    {#- Block for the `spacy` section style. -#}
     <table>
       <thead>
         <tr>
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
index fc212db9..239f7a55 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja
@@ -1,11 +1,26 @@
+{#- 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. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Modules:") }}</span></p>
     <table>
       <thead>
@@ -30,6 +45,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style scoped %}
+    {#- Block for the `list` section style. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Modules:") }}</span></p>
     <ul>
       {% for module in section.value %}
@@ -45,6 +61,7 @@
   {% endblock list_style %}
 {% elif config.docstring_section_style == "spacy" %}
   {% block spacy_style scoped %}
+    {#- Block for the `spacy` section style. -#}
     <table>
       <thead>
         <tr>
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
index c3d4af97..7daabeda 100644
--- 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
@@ -1,11 +1,26 @@
+{#- 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. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Other Parameters:") }}</span></p>
     <table>
       <thead>
@@ -38,6 +53,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style scoped %}
+    {#- Block for the `list` section style. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Other Parameters:") }}</span></p>
     <ul>
       {% for parameter in section.value %}
@@ -58,6 +74,7 @@
   {% endblock list_style %}
 {% elif config.docstring_section_style == "spacy" %}
   {% block spacy_style scoped %}
+    {#- Block for the `spacy` section style. -#}
     <table>
       <thead>
         <tr>
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
index f411e114..3de6f4a9 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja
@@ -1,11 +1,26 @@
+{#- 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. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Parameters:") }}</span></p>
     <table>
       <thead>
@@ -48,6 +63,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style scoped %}
+    {#- Block for the `list` section style. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Parameters:") }}</span></p>
     <ul>
       {% for parameter in section.value %}
@@ -73,6 +89,7 @@
   {% endblock list_style %}
 {% elif config.docstring_section_style == "spacy" %}
   {% block spacy_style scoped %}
+    {#- Block for the `spacy` section style. -#}
     <table>
       <thead>
         <tr>
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
index 12ff1496..79024057 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja
@@ -1,11 +1,26 @@
+{#- 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. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Raises:") }}</span></p>
     <table>
       <thead>
@@ -36,6 +51,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style scoped %}
+    {#- Block for the `list` section style. -#}
     <p><span class="doc-section-title">{{ lang.t(section.title) or lang.t("Raises:") }}</span></p>
     <ul>
       {% for raises in section.value %}
@@ -55,6 +71,7 @@
   {% endblock list_style %}
 {% elif config.docstring_section_style == "spacy" %}
   {% block spacy_style scoped %}
+    {#- Block for the `spacy` section style. -#}
     <table>
       <thead>
         <tr>
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
index 13e0ea30..2fcce8ef 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html.jinja
@@ -1,11 +1,26 @@
+{#- 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 %}
     <p><span class="doc-section-title">{{ section.title or lang.t("Receives:") }}</span></p>
     <table>
@@ -39,6 +54,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style scoped %}
+    {#- Block for the `list` section style. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Receives:") }}</span></p>
     <ul>
       {% for receives in section.value %}
@@ -61,6 +77,7 @@
   {% endblock list_style %}
 {% elif config.docstring_section_style == "spacy" %}
   {% block spacy_style scoped %}
+    {#- Block for the `spacy` section style. -#}
     <table>
       <thead>
         <tr>
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
index 9a330780..8feeb054 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html.jinja
@@ -1,11 +1,26 @@
+{#- 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 %}
     <p><span class="doc-section-title">{{ section.title or lang.t("Returns:") }}</span></p>
     <table>
@@ -39,6 +54,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style scoped %}
+    {#- Block for the `list` section style. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Returns:") }}</span></p>
     <ul>
       {% for returns in section.value %}
@@ -61,6 +77,7 @@
   {% endblock list_style %}
 {% elif config.docstring_section_style == "spacy" %}
   {% block spacy_style scoped %}
+    {#- Block for the `spacy` section style. -#}
     <table>
       <thead>
         <tr>
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
index b8ed3851..6143257d 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html.jinja
@@ -1,11 +1,26 @@
+{#- 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. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Warns:") }}</span></p>
     <table>
       <thead>
@@ -36,6 +51,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style scoped %}
+    {#- Block for the `list` section style. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Warns:") }}</span></p>
     <ul>
       {% for warns in section.value %}
@@ -55,6 +71,7 @@
   {% endblock list_style %}
 {% elif config.docstring_section_style == "spacy" %}
   {% block spacy_style scoped %}
+    {#- Block for the `spacy` section style. -#}
     <table>
       <thead>
         <tr>
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
index 6172a254..d326c1fe 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html.jinja
@@ -1,11 +1,26 @@
+{#- 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 %}
     <p><span class="doc-section-title">{{ section.title or lang.t("Yields:") }}</span></p>
     <table>
@@ -39,6 +54,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style scoped %}
+    {#- Block for the `list` section style. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Yields:") }}</span></p>
     <ul>
       {% for yields in section.value %}
@@ -61,6 +77,7 @@
   {% endblock list_style %}
 {% elif config.docstring_section_style == "spacy" %}
   {% block spacy_style scoped %}
+    {#- Block for the `spacy` section style. -#}
     <table>
       <thead>
         <tr>
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja
index c219f636..5a216e3e 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja
@@ -1,7 +1,28 @@
+{#- 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 -%}
@@ -24,6 +45,15 @@
 {%- 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" -%}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja
index c4d0f1fc..4f36059e 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja
@@ -1,8 +1,24 @@
+{#- Template for Python functions.
+
+This template renders a Python function or method.
+
+Context:
+  function (griffe.dataclasses.Function): The function to render.
+  root (bool): Whether this is the root object, injected with `:::` in a Markdown page.
+  heading_level (int): The HTML heading level to use.
+  config (dict): The configuration options.
+-#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
   {{ log.debug("Rendering " + function.path) }}
 {% endblock logs %}
 
 {% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
 
 <div class="doc doc-object doc-function">
   {% with obj = function, html_id = function.path %}
@@ -18,7 +34,9 @@
     {% 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(
@@ -30,6 +48,10 @@
         ) %}
 
         {% block heading scoped %}
+          {#- Heading block.
+          
+          This block renders the heading for the function.
+          -#}
           {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-{{ symbol_type }}"></code>{% endif %}
           {% if config.separate_signature %}
             <span class="doc doc-object-name doc-function-name">{{ function_name }}</span>
@@ -41,6 +63,10 @@
         {% 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 %}
@@ -49,6 +75,10 @@
       {% 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 }}
@@ -73,13 +103,27 @@
 
     <div class="doc doc-contents {% if root %}first{% 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 %}
             <details class="quote">
               <summary>{{ lang.t("Source code in") }} <code>
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja
index bcdc112b..dced4913 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja
@@ -1,5 +1,20 @@
+{#- 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 %}
   <span class="doc doc-labels">
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja
index dd3fe800..5b643726 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja
@@ -1,6 +1,12 @@
+{#- 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 %}
-<!-- Import translations for given language and fallback -->
+
 {% set lang_pth = "languages/" ~ locale | get_template %}
 {% if lang_pth is existing_template %}
     {% import lang_pth as lang %}
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
index 5a771d30..d988b6ab 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html.jinja
@@ -1,6 +1,12 @@
-<!-- Translations: English -->
+{#- 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:",
@@ -36,4 +42,4 @@
   "Warns:": "Warns:",
   "YIELDS": "YIELDS",
   "Yields:": "Yields:",
-}[key] }}{% endmacro %}
\ No newline at end of file
+}[key] }}{% endmacro %}
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
index 748fd8b7..a6b7728b 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja
@@ -1,6 +1,12 @@
-<!-- Translations: Japanese -->
+{#- 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:": "属性:",
@@ -36,4 +42,4 @@
   "Warns:": "警告:",
   "YIELDS": "返す",
   "Yields:": "返す:",
-}[key] }}{% endmacro %}
\ No newline at end of file
+}[key] }}{% endmacro %}
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
index 772e33cd..f748b83c 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja
@@ -1,6 +1,12 @@
-<!-- Translations: Chinese -->
+{#- 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:": "属性:",
@@ -36,4 +42,4 @@
   "WARNS": "警告",
   "YIELDS": "产生",
   "Yields:": "产生:",
-}[key] }}{% endmacro %}
\ No newline at end of file
+}[key] }}{% endmacro %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja
index 02665e20..06870b98 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja
@@ -1,4 +1,19 @@
+{#- Template for Python modules.
+
+This template renders a Python module.
+
+Context:
+  module (griffe.dataclasses.Module): The module to render.
+  root (bool): Whether this is the root object, injected with `:::` in a Markdown page.
+  heading_level (int): The HTML heading level to use.
+  config (dict): The configuration options.
+-#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
   {{ log.debug("Rendering " + module.path) }}
 {% endblock logs %}
 
@@ -27,6 +42,10 @@
         ) %}
 
         {% block heading scoped %}
+          {#- Heading block.
+          
+          This block renders the heading for the module.
+          -#}
           {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-module"></code>{% endif %}
           {% if config.separate_signature %}
             <span class="doc doc-object-name doc-module-name">{{ module_name }}</span>
@@ -36,6 +55,10 @@
         {% 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 %}
@@ -58,13 +81,27 @@
 
     <div class="doc doc-contents {% if root %}first{% 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 %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja
index d5bd4220..2d87986c 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja
@@ -1,7 +1,22 @@
+{#- Template for signatures.
+
+This template renders the signature of a function or method.
+It iterates over the parameters of the function to rebuild the signature.
+The signature is the list of parameters of a function or method, including their names, default values, and annotations.
+
+Context:
+  function (griffe.dataclasses.Function): The function or method to render.
+  config (dict): The configuration options.
+-#}
+
 {%- if config.show_signature -%}
-  {% block logs scoped %}
+  {%- block logs scoped -%}
+    {#- Logging block.
+    
+    This block can be used to log debug messages, deprecation messages, warnings, etc.
+    -#}
     {{ log.debug("Rendering signature") }}
-  {% endblock logs %}
+  {%- endblock logs -%}
   {%- with -%}
 
     {%- set ns = namespace(
@@ -16,6 +31,7 @@
     {%- for parameter in function.parameters -%}
       {%- if parameter.name not in ("self", "cls") or loop.index0 > 0 or not (function.parent and function.parent.is_class) -%}
 
+        {#- Handle parameter kind. -#}
         {%- if parameter.kind.value == "positional-only" -%}
           {%- set ns.has_pos_only = True -%}
         {%- else -%}
@@ -27,6 +43,7 @@
           {%- endif -%}
         {%- endif -%}
 
+        {#- Prepare type annotation. -#}
         {%- if config.show_signature_annotations and parameter.annotation is not none -%}
           {%- set ns.equal = " = " -%}
           {%- if config.separate_signature and config.signature_crossrefs -%}
@@ -41,14 +58,17 @@
           {%- set ns.annotation = "" -%}
         {%- endif -%}
 
+        {#- Prepare default value. -#}
         {%- if parameter.default is not none and parameter.kind.value != "variadic positional" and parameter.kind.value != "variadic keyword" -%}
           {%- set default = ns.equal + parameter.default|safe -%}
         {%- endif -%}
 
+        {#- TODO: Move inside kind handling above? -#}
         {%- if parameter.kind.value == "variadic positional" -%}
           {%- set ns.render_kw_only_separator = False -%}
         {%- endif -%}
 
+        {#- Render name, annotation and default. -#}
         {% if parameter.kind.value == "variadic positional" %}*{% elif parameter.kind.value == "variadic keyword" %}**{% endif -%}
         {{ parameter.name }}{{ ns.annotation }}{{ default }}
         {%- if not loop.last %}, {% endif -%}
@@ -56,6 +76,8 @@
       {%- endif -%}
     {%- endfor -%}
     )
+
+    {#- Render return type. -#}
     {%- if config.show_signature_annotations
         and function.annotation
         and not (config.merge_init_into_class and function.name == "__init__" )
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/summary.html.jinja
index 2390659d..5770fdb0 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/summary.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary.html.jinja
@@ -1,2 +1,8 @@
+{#- Template for auto-summaries. -#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
 {% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary/attributes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/summary/attributes.html.jinja
index 2390659d..cb966fb1 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/summary/attributes.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary/attributes.html.jinja
@@ -1,2 +1,8 @@
+{#- Summary of attributes. -#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
 {% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary/classes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/summary/classes.html.jinja
index 2390659d..94456775 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/summary/classes.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary/classes.html.jinja
@@ -1,2 +1,8 @@
+{#- Summary of classes. -#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
 {% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary/functions.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/summary/functions.html.jinja
index 2390659d..5e8305aa 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/summary/functions.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary/functions.html.jinja
@@ -1,2 +1,8 @@
+{#- Summary of functions/methods. -#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
 {% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary/modules.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/summary/modules.html.jinja
index 2390659d..04387b32 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/summary/modules.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary/modules.html.jinja
@@ -1,2 +1,8 @@
+{#- Summary of modules. -#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
 {% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja
index c3586f6a..8df20e1c 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja
@@ -1,8 +1,22 @@
+{#- 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() }}
 {% endblock %}
 
 {% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
 
 <table class="field-list">
   <colgroup>
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
index 339a0cee..4b416b65 100644
--- 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
@@ -1,8 +1,22 @@
+{#- 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. -#}
 
 <table class="field-list">
   <colgroup>
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
index ad69e78a..10bbd7ba 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja
@@ -1,8 +1,22 @@
+{#- 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. -#}
 
 <table class="field-list">
   <colgroup>
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
index ae7f38dc..f350bc97 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja
@@ -1,8 +1,22 @@
+{#- 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. -#}
 
 <table class="field-list">
   <colgroup>
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
index a37db154..804a04a0 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja
@@ -1,8 +1,22 @@
+{#- 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. -#}
 
 <table class="field-list">
   <colgroup>
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
index 8f7dbd9b..0074327a 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja
@@ -1,8 +1,22 @@
+{#- 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. -#}
 
 <table class="field-list">
   <colgroup>
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
index 8ae5eb17..88308b68 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja
@@ -1,8 +1,22 @@
+{#- 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. -#}
 
 <table class="field-list">
   <colgroup>
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
index 44670856..bd43955d 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja
@@ -1,8 +1,22 @@
+{#- 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. -#}
 
 <table class="field-list">
   <colgroup>
diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html.jinja
index 9c03b815..5b643726 100644
--- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html.jinja
@@ -1,6 +1,12 @@
+{#- 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 %}
-<!-- Import translations for given language and fallback -->
+
 {% set lang_pth = "languages/" ~ locale | get_template %}
 {% if lang_pth is existing_template %}
     {% import lang_pth as lang %}
@@ -9,4 +15,4 @@
 {% else %}
     {% import "languages/en"|get_template as lang %}
     {% macro t(key) %}{{ lang.t(key) }}{% endmacro %}
-{% endif %}
\ No newline at end of file
+{% endif %}