fixup! docs: Document Jinja templates

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 %}

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 %}

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>

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 %}

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 %}

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 %}

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 %}

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 %}

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 %}

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 %}

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 %}

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 %}

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 %}

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 %}

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 %}

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 %}

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 %}

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" -%}