docs: Document Jinja templates

Issue-149: #149
PR-156: #156

Author: pawamoy

src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja

@@ -1,4 +1,20 @@
+{#- Template for Python attributes.
+
+This template renders a Python attribute (or variable).
+This can be a module attribute or a class attribute.
+
+Context:
+  attribute (griffe.dataclasses.Attribute): The attribute to render.
+  root (bool): Whether this is the root object, injected with `:::` in a Markdown page.
+  heading_level (int): The HTML heading level to use.
+  config (dict): The configuration options.
+-#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
   {{ log.debug("Rendering " + attribute.path) }}
 {% endblock logs %}
 
@@ -27,6 +43,10 @@
         ) %}
 
         {% block heading scoped %}
+          {#- Heading block.
+          
+          This block renders the heading for the attribute.
+          -#}
           {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>{% endif %}
           {% if config.separate_signature %}
             <span class="doc doc-object-name doc-attribute-name">{{ attribute_name }}</span>
@@ -39,6 +59,10 @@
         {% endblock heading %}
 
         {% block labels scoped %}
+          {#- Labels block.
+          
+          This block renders the labels for the attribute.
+          -#}
           {% with labels = attribute.labels %}
             {% include "labels"|get_template with context %}
           {% endwith %}
@@ -47,6 +71,10 @@
       {% endfilter %}
 
       {% block signature scoped %}
+        {#- Signature block.
+        
+        This block renders the signature for the attribute.
+        -#}
         {% if config.separate_signature %}
           {% filter format_attribute(attribute, config.line_length, crossrefs=config.signature_crossrefs) %}
             {{ attribute.name }}
@@ -70,7 +98,17 @@
 
     <div class="doc doc-contents {% if root %}first{% endif %}">
       {% block contents scoped %}
+        {#- Contents block.
+        
+        This block renders the contents of the attribute.
+        It contains other blocks that users can override.
+        Overriding the contents block allows to rearrange the order of the blocks.
+        -#}
         {% block docstring scoped %}
+          {#- Docstring block.
+          
+          This block renders the docstring for the attribute.
+          -#}
           {% with docstring_sections = attribute.docstring.parsed %}
             {% include "docstring"|get_template with context %}
           {% endwith %}

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 %}
 
@@ -27,6 +42,10 @@
         ) %}
 
         {% block heading scoped %}
+          {#- Heading block.
+          
+          This block renders the heading for the class.
+          -#}
           {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>{% endif %}
           {% if config.separate_signature %}
             <span class="doc doc-object-name doc-class-name">{{ class_name }}</span>
@@ -42,6 +61,10 @@
         {% endblock heading %}
 
         {% block labels scoped %}
+          {#- Labels block.
+          
+          This block renders the labels for the class.
+          -#}
           {% with labels = class.labels %}
             {% include "labels"|get_template with context %}
           {% endwith %}
@@ -50,6 +73,10 @@
       {% endfilter %}
 
       {% block signature scoped %}
+        {#- Signature block.
+        
+        This block renders the signature for the class.
+        -#}
         {% if config.separate_signature and config.merge_init_into_class %}
           {% if "__init__" in class.all_members %}
             {% with function = class.all_members["__init__"] %}
@@ -76,7 +103,17 @@
 
     <div class="doc doc-contents {% if root %}first{% endif %}">
       {% block contents scoped %}
+        {#- Contents block.
+        
+        This block renders the contents of the class.
+        It contains other blocks that users can override.
+        Overriding the contents block allows to rearrange the order of the blocks.
+        -#}
         {% block bases scoped %}
+          {#- Class bases block.
+          
+          This block renders the bases for the class.
+          -#}
           {% if config.show_bases and class.bases %}
             <p class="doc doc-class-bases">
               Bases: {% for expression in class.bases -%}
@@ -87,6 +124,10 @@
         {% endblock bases %}
 
         {% block docstring scoped %}
+          {#- Docstring block.
+          
+          This block renders the docstring for the class.
+          -#}
           {% with docstring_sections = class.docstring.parsed %}
             {% include "docstring"|get_template with context %}
           {% endwith %}
@@ -100,6 +141,10 @@
         {% endblock docstring %}
 
         {% block source scoped %}
+          {#- Source block.
+          
+          This block renders the source code for the class.
+          -#}
           {% if config.show_source %}
             {% if config.merge_init_into_class %}
               {% if "__init__" in class.all_members and class.all_members["__init__"].source %}
@@ -132,6 +177,10 @@
         {% endblock source %}
 
         {% block children scoped %}
+          {#- Children block.
+          
+          This block renders the children (members) of the class.
+          -#}
           {% set root = False %}
           {% set heading_level = heading_level + 1 %}
           {% include "children"|get_template with context %}
@@ -140,5 +189,4 @@
     </div>
 
   {% endwith %}
-
 </div>

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,26 @@
+{#- Template for "Classes" sections in docstrings.
+
+This template renders a list of documented classes in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+  section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
   {{ log.debug("Rendering classes section") }}
 {% endblock logs %}
 
 {% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
 
 {% if config.docstring_section_style == "table" %}
   {% block table_style scoped %}
+    {#- Block for the `table` section style. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Classes:") }}</span></p>
     <table>
       <thead>
@@ -30,6 +45,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style scoped %}
+    {#- Block for the `list` section style. -#}
     <p><span class="doc-section-title">{{ section.title or lang.t("Classes:") }}</span></p>
     <ul>
       {% for class in section.value %}
@@ -45,6 +61,7 @@
   {% endblock list_style %}
 {% elif config.docstring_section_style == "spacy" %}
   {% block spacy_style scoped %}
+    {#- Block for the `spacy` section style. -#}
     <table>
       <thead>
         <tr>

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

@@ -1,8 +1,22 @@
+{#- Template for "Examples" sections in docstrings.
+
+This template renders a list of documented examples.
+It alternates between rendering text and code examples.
+
+Context:
+  section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
+-#}
+
 {% block logs scoped %}
+  {#- Logging block.
+  
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
   {{ log.debug("Rendering examples section") }}
 {% endblock logs %}
 
 {% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
 
 <p><span class="doc-section-title">{{ section.title or lang.t("Examples:") }}</span></p>
 {% for section_type, sub_section in section.value %}