docs: Document Jinja templates

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

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

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

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

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>
+</details>

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>

src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja

@@ -1,11 +1,25 @@
+{#- Template for "Classes" sections in docstrings.
+
+This template renders a list of documented classes in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+    section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
   {{ log.debug("Rendering classes section") }}
 {% endblock logs %}
 
 {% import "language"|get_template as lang with context %}
 
 {% 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>

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

src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja

@@ -1,11 +1,25 @@
+{#- Template for "Functions" sections in docstrings.
+
+This template renders a list of documented functions in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+    section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
   {{ log.debug("Rendering functions section") }}
 {% endblock logs %}
 
 {% import "language"|get_template as lang with context %}
 
 {% 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>

src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja

@@ -1,11 +1,25 @@
+{#- Template for "Modules" sections in docstrings.
+
+This template renders a list of documented modules in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+    section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
   {{ log.debug("Rendering modules section") }}
 {% endblock logs %}
 
 {% import "language"|get_template as lang with context %}
 
 {% 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>

src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html.jinja

@@ -1,11 +1,25 @@
+{#- Template for "Other parameters" sections in docstrings.
+
+This template renders a list of documented other parameters in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+    section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
   {{ log.debug("Rendering other parameters section") }}
 {% endblock logs %}
 
 {% import "language"|get_template as lang with context %}
 
 {% 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>

src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja

@@ -1,11 +1,25 @@
+{#- Template for "Parameters" sections in docstrings.
+
+This template renders a list of documented parameters in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+    section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
   {{ log.debug("Rendering parameters section") }}
 {% endblock logs %}
 
 {% import "language"|get_template as lang with context %}
 
 {% 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>