From 13b5d95b3ef6dcee99bfa74005d504203da41451 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= <dev@pawamoy.fr>
Date: Sun, 28 Apr 2024 18:02:52 +0200
Subject: [PATCH 1/4] docs: Document Jinja templates

---
 .../material/_base/attribute.html.jinja         | 16 ++++++++++++++++
 .../material/_base/children.html.jinja          | 16 ++++++++++++++++
 .../templates/material/_base/class.html.jinja   | 15 +++++++++++++++
 .../material/_base/docstring.html.jinja         | 17 +++++++++++++++++
 .../_base/docstring/admonition.html.jinja       | 15 ++++++++++++++-
 .../_base/docstring/attributes.html.jinja       | 17 +++++++++++++++++
 .../material/_base/docstring/classes.html.jinja | 16 ++++++++++++++++
 .../_base/docstring/examples.html.jinja         | 13 +++++++++++++
 .../_base/docstring/functions.html.jinja        | 16 ++++++++++++++++
 .../material/_base/docstring/modules.html.jinja | 16 ++++++++++++++++
 .../_base/docstring/other_parameters.html.jinja | 16 ++++++++++++++++
 .../_base/docstring/parameters.html.jinja       | 16 ++++++++++++++++
 .../material/_base/docstring/raises.html.jinja  | 16 ++++++++++++++++
 .../_base/docstring/receives.html.jinja         | 16 ++++++++++++++++
 .../material/_base/docstring/returns.html.jinja | 16 ++++++++++++++++
 .../material/_base/docstring/warns.html.jinja   | 16 ++++++++++++++++
 .../material/_base/docstring/yields.html.jinja  | 16 ++++++++++++++++
 .../material/_base/expression.html.jinja        |  4 ++++
 .../material/_base/function.html.jinja          |  4 ++++
 .../templates/material/_base/labels.html.jinja  |  4 ++++
 .../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 ++++++++--
 .../templates/material/_base/module.html.jinja  |  4 ++++
 .../material/_base/signature.html.jinja         |  4 ++++
 .../templates/material/_base/summary.html.jinja |  4 ++++
 .../_base/summary/attributes.html.jinja         |  6 ++++++
 .../material/_base/summary/classes.html.jinja   |  6 ++++++
 .../material/_base/summary/functions.html.jinja |  6 ++++++
 .../material/_base/summary/modules.html.jinja   |  6 ++++++
 31 files changed, 347 insertions(+), 8 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..796a104b 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 %}
 
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..0484a303 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..50e814de 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 %}
 
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..3d9ed5c4 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..4a6376ab 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..03f52d7f 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..21c1ccfd 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,4 +1,17 @@
+{#- 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 %}
 
@@ -6,6 +19,7 @@
 
 {% 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 +44,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 +60,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..125860df 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,4 +1,17 @@
+{#- 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 %}
 
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..cf0435e2 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,4 +1,17 @@
+{#- 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 %}
 
@@ -6,6 +19,7 @@
 
 {% 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 +46,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 +64,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..31e23900 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,4 +1,17 @@
+{#- 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 %}
 
@@ -6,6 +19,7 @@
 
 {% 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 +44,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 +60,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..d2c076c4 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,4 +1,17 @@
+{#- 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 %}
 
@@ -6,6 +19,7 @@
 
 {% 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 +52,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 +73,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..814e8a2d 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,4 +1,17 @@
+{#- 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 %}
 
@@ -6,6 +19,7 @@
 
 {% 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 +62,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 +88,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..a5e907b4 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,4 +1,17 @@
+{#- 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 %}
 
@@ -6,6 +19,7 @@
 
 {% 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 +50,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 +70,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..cb6d67a1 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,4 +1,17 @@
+{#- 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 %}
 
@@ -6,6 +19,7 @@
 
 {% 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 +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("Receives:") }}</span></p>
     <ul>
       {% for receives in section.value %}
@@ -61,6 +76,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..66a3b63a 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,4 +1,17 @@
+{#- 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 %}
 
@@ -6,6 +19,7 @@
 
 {% 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 +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("Returns:") }}</span></p>
     <ul>
       {% for returns in section.value %}
@@ -61,6 +76,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..845d9188 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,4 +1,17 @@
+{#- 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 %}
 
@@ -6,6 +19,7 @@
 
 {% 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 +50,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 +70,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..79b663c8 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,4 +1,17 @@
+{#- 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 %}
 
@@ -6,6 +19,7 @@
 
 {% 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 +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("Yields:") }}</span></p>
     <ul>
       {% for yields in section.value %}
@@ -61,6 +76,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..ebe6fb26 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja
@@ -1,4 +1,8 @@
 {% 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) -%}
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..94da698f 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja
@@ -1,4 +1,8 @@
 {% 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 %}
 
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..e1349312 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,9 @@
 {% 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..0bd2dc65 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 -->
+{#- 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..e942d76a 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,8 @@
 {% 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 %}
 
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..3f55da85 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja
@@ -1,5 +1,9 @@
 {%- if config.show_signature -%}
   {% block logs scoped %}
+    {#- Logging block.
+    
+    This block can be used to log debug messages, deprecation messages, warnings, etc.
+    -#}
     {{ log.debug("Rendering signature") }}
   {% endblock logs %}
   {%- with -%}
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..c267b17c 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,6 @@
 {% 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 %}

From 6df2dccd403a2f0aa1d283ff09a83476002b6387 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= <dev@pawamoy.fr>
Date: Sun, 28 Apr 2024 20:50:43 +0200
Subject: [PATCH 2/4] fixup! docs: Document Jinja templates

---
 .../material/_base/attribute.html.jinja       | 30 +++++++++++--
 .../material/_base/children.html.jinja        |  8 ++--
 .../templates/material/_base/class.html.jinja | 43 ++++++++++++++++---
 .../material/_base/docstring.html.jinja       |  8 ++--
 .../_base/docstring/admonition.html.jinja     |  2 +-
 .../_base/docstring/attributes.html.jinja     |  2 +-
 .../_base/docstring/classes.html.jinja        |  2 +-
 .../_base/docstring/examples.html.jinja       |  2 +-
 .../_base/docstring/functions.html.jinja      |  2 +-
 .../_base/docstring/modules.html.jinja        |  2 +-
 .../docstring/other_parameters.html.jinja     |  2 +-
 .../_base/docstring/parameters.html.jinja     |  2 +-
 .../_base/docstring/raises.html.jinja         |  2 +-
 .../_base/docstring/receives.html.jinja       |  2 +-
 .../_base/docstring/returns.html.jinja        |  2 +-
 .../material/_base/docstring/warns.html.jinja |  2 +-
 .../_base/docstring/yields.html.jinja         |  2 +-
 .../material/_base/expression.html.jinja      | 26 +++++++++++
 .../material/_base/function.html.jinja        | 40 +++++++++++++++++
 .../material/_base/labels.html.jinja          | 11 +++++
 .../material/_base/languages/en.html.jinja    |  2 +-
 .../material/_base/module.html.jinja          | 33 ++++++++++++++
 .../material/_base/signature.html.jinja       | 11 +++++
 .../material/_base/summary.html.jinja         |  2 +
 24 files changed, 209 insertions(+), 31 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 796a104b..11bc4e77 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja
@@ -4,10 +4,10 @@ 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.
+  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 %}
@@ -43,6 +43,10 @@ Context:
         ) %}
 
         {% 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>
@@ -55,6 +59,10 @@ Context:
         {% 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 %}
@@ -63,6 +71,10 @@ Context:
       {% 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 }}
@@ -86,7 +98,17 @@ Context:
 
     <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 0484a303..b0ec4007 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja
@@ -4,10 +4,10 @@ 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.
+  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 %}
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 50e814de..bb32a91c 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja
@@ -3,10 +3,10 @@
 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.
+  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 %}
@@ -42,6 +42,10 @@ Context:
         ) %}
 
         {% 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>
@@ -57,6 +61,10 @@ Context:
         {% 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 %}
@@ -65,6 +73,10 @@ Context:
       {% 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__"] %}
@@ -91,7 +103,17 @@ Context:
 
     <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 -%}
@@ -102,6 +124,10 @@ Context:
         {% 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 %}
@@ -115,6 +141,10 @@ Context:
         {% 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 %}
@@ -147,6 +177,10 @@ Context:
         {% 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 %}
@@ -155,5 +189,4 @@ Context:
     </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 3d9ed5c4..f5095eb4 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja
@@ -5,10 +5,10 @@ Griffe parses docstrings into a list of sections, each with a `kind` and a `valu
 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.
+  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 %}
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 4a6376ab..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
@@ -3,7 +3,7 @@
 This template renders admonitions using the `details` HTML element.
 
 Context:
-    section (griffe.docstrings.dataclasses.DocstringSectionAdmonition): The section to render.
+  section (griffe.docstrings.dataclasses.DocstringSectionAdmonition): The section to render.
 -#}
 
 {% block logs scoped %}
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 03f52d7f..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
@@ -4,7 +4,7 @@ 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.
+  section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
 -#}
 
 {% block logs scoped %}
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 21c1ccfd..b6963d17 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
@@ -4,7 +4,7 @@ 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.
+  section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
 -#}
 
 {% block logs scoped %}
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 125860df..9c330ec7 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
@@ -4,7 +4,7 @@ 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.
+  section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
 -#}
 
 {% block logs scoped %}
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 cf0435e2..40ccb3b0 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
@@ -4,7 +4,7 @@ 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.
+  section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
 -#}
 
 {% block logs scoped %}
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 31e23900..10a50647 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
@@ -4,7 +4,7 @@ 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.
+  section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
 -#}
 
 {% block logs scoped %}
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 d2c076c4..9b531914 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
@@ -4,7 +4,7 @@ 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.
+  section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
 -#}
 
 {% block logs scoped %}
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 814e8a2d..4c5d2681 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
@@ -4,7 +4,7 @@ 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.
+  section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
 -#}
 
 {% block logs scoped %}
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 a5e907b4..6f81adc9 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
@@ -4,7 +4,7 @@ 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.
+  section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
 -#}
 
 {% block logs scoped %}
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 cb6d67a1..d2d21e0f 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
@@ -4,7 +4,7 @@ This template renders a list of documented received values (generators) in the f
 specified with the [`docstring_section_style`][] configuration option.
 
 Context:
-    section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+  section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
 -#}
 
 {% block logs scoped %}
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 66a3b63a..b6573d94 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
@@ -4,7 +4,7 @@ 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.
+  section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
 -#}
 
 {% block logs scoped %}
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 845d9188..c9294aaf 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
@@ -4,7 +4,7 @@ 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.
+  section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
 -#}
 
 {% block logs scoped %}
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 79b663c8..30326a3d 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
@@ -4,7 +4,7 @@ This template renders a list of documented yielded values (generators) in the fo
 specified with the [`docstring_section_style`][] configuration option.
 
 Context:
-    section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+  section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
 -#}
 
 {% block logs scoped %}
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 ebe6fb26..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,3 +1,9 @@
+{#- Template for expressions.
+
+This template renders a Griffe expression,
+which is a tree-like structure representing a Python expression.
+-#}
+
 {% block logs scoped %}
   {#- Logging block.
   
@@ -6,6 +12,17 @@
 {% 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 -%}
@@ -28,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 94da698f..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,3 +1,14 @@
+{#- 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.
   
@@ -7,6 +18,7 @@
 {% 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 %}
@@ -22,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(
@@ -34,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>
@@ -45,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 %}
@@ -53,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 }}
@@ -77,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 e1349312..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,3 +1,14 @@
+{#- 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.
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 0bd2dc65..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,4 +1,4 @@
-{#- English translations. -#}
+{#- Macro for English translations. -#}
 
 {% block logs scoped %}
   {#- Logging block.
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 e942d76a..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,3 +1,14 @@
+{#- 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.
   
@@ -31,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>
@@ -40,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 %}
@@ -62,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 3f55da85..0835d987 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja
@@ -1,3 +1,14 @@
+{#- 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 %}
     {#- Logging block.
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 c267b17c..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,3 +1,5 @@
+{#- Template for auto-summaries. -#}
+
 {% block logs scoped %}
   {#- Logging block.
   

From 1ff3ac0810b8c580d3b71a4dc6b13646d1f14c24 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= <dev@pawamoy.fr>
Date: Sun, 28 Apr 2024 20:57:45 +0200
Subject: [PATCH 3/4] fixup! docs: Document Jinja templates

---
 .../material/_base/docstring/classes.html.jinja    |  1 +
 .../material/_base/docstring/examples.html.jinja   |  1 +
 .../material/_base/docstring/functions.html.jinja  |  1 +
 .../material/_base/docstring/modules.html.jinja    |  1 +
 .../_base/docstring/other_parameters.html.jinja    |  1 +
 .../material/_base/docstring/parameters.html.jinja |  1 +
 .../material/_base/docstring/raises.html.jinja     |  1 +
 .../material/_base/docstring/receives.html.jinja   |  1 +
 .../material/_base/docstring/returns.html.jinja    |  1 +
 .../material/_base/docstring/warns.html.jinja      |  1 +
 .../material/_base/docstring/yields.html.jinja     |  1 +
 .../_base/docstring/attributes.html.jinja          | 14 ++++++++++++++
 .../_base/docstring/other_parameters.html.jinja    | 14 ++++++++++++++
 .../_base/docstring/parameters.html.jinja          | 14 ++++++++++++++
 .../readthedocs/_base/docstring/raises.html.jinja  | 14 ++++++++++++++
 .../_base/docstring/receives.html.jinja            | 14 ++++++++++++++
 .../readthedocs/_base/docstring/returns.html.jinja | 14 ++++++++++++++
 .../readthedocs/_base/docstring/warns.html.jinja   | 14 ++++++++++++++
 .../readthedocs/_base/docstring/yields.html.jinja  | 14 ++++++++++++++
 .../readthedocs/_base/language.html.jinja          | 10 ++++++++--
 20 files changed, 131 insertions(+), 2 deletions(-)

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 b6963d17..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
@@ -16,6 +16,7 @@ Context:
 {% 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 %}
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 9c330ec7..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
@@ -16,6 +16,7 @@ Context:
 {% 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 40ccb3b0..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
@@ -16,6 +16,7 @@ Context:
 {% 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 %}
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 10a50647..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
@@ -16,6 +16,7 @@ Context:
 {% 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 %}
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 9b531914..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
@@ -16,6 +16,7 @@ Context:
 {% 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 %}
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 4c5d2681..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
@@ -16,6 +16,7 @@ Context:
 {% 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 %}
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 6f81adc9..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
@@ -16,6 +16,7 @@ Context:
 {% 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 %}
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 d2d21e0f..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
@@ -16,6 +16,7 @@ Context:
 {% 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 %}
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 b6573d94..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
@@ -16,6 +16,7 @@ Context:
 {% 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 %}
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 c9294aaf..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
@@ -16,6 +16,7 @@ Context:
 {% 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 %}
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 30326a3d..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
@@ -16,6 +16,7 @@ Context:
 {% 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 %}
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 %}

From d57ad294d4c863a6477cf3c1bb2c22ca24ee8d81 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= <dev@pawamoy.fr>
Date: Mon, 29 Apr 2024 00:06:04 +0200
Subject: [PATCH 4/4] fixup! docs: Document Jinja templates

---
 .../templates/material/_base/signature.html.jinja     | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

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 0835d987..2d87986c 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja
@@ -10,13 +10,13 @@ Context:
 -#}
 
 {%- 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(
@@ -31,6 +31,7 @@ Context:
     {%- 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 -%}
@@ -42,6 +43,7 @@ Context:
           {%- 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 -%}
@@ -56,14 +58,17 @@ Context:
           {%- 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 -%}
@@ -71,6 +76,8 @@ Context:
       {%- endif -%}
     {%- endfor -%}
     )
+
+    {#- Render return type. -#}
     {%- if config.show_signature_annotations
         and function.annotation
         and not (config.merge_init_into_class and function.name == "__init__" )