Skip to content

Commit 583b8fe

Browse files
pawamoypawamoy
authored
docs: Document Jinja templates
Issue-149: mkdocstrings#149 PR-156: mkdocstrings#156
1 parent e7f997b commit 583b8fe

40 files changed

+666
-13
lines changed

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

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,20 @@
1+
{#- Template for Python attributes.
2+
3+
This template renders a Python attribute (or variable).
4+
This can be a module attribute or a class attribute.
5+
6+
Context:
7+
attribute (griffe.dataclasses.Attribute): The attribute to render.
8+
root (bool): Whether this is the root object, injected with `:::` in a Markdown page.
9+
heading_level (int): The HTML heading level to use.
10+
config (dict): The configuration options.
11+
-#}
12+
113
{% block logs scoped %}
14+
{#- Logging block.
15+
16+
This block can be used to log debug messages, deprecation messages, warnings, etc.
17+
-#}
218
{{ log.debug("Rendering " + attribute.path) }}
319
{% endblock logs %}
420

@@ -27,6 +43,10 @@
2743
) %}
2844

2945
{% block heading scoped %}
46+
{#- Heading block.
47+
48+
This block renders the heading for the attribute.
49+
-#}
3050
{% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>{% endif %}
3151
{% if config.separate_signature %}
3252
<span class="doc doc-object-name doc-attribute-name">{{ attribute_name }}</span>
@@ -39,6 +59,10 @@
3959
{% endblock heading %}
4060

4161
{% block labels scoped %}
62+
{#- Labels block.
63+
64+
This block renders the labels for the attribute.
65+
-#}
4266
{% with labels = attribute.labels %}
4367
{% include "labels"|get_template with context %}
4468
{% endwith %}
@@ -47,6 +71,10 @@
4771
{% endfilter %}
4872

4973
{% block signature scoped %}
74+
{#- Signature block.
75+
76+
This block renders the signature for the attribute.
77+
-#}
5078
{% if config.separate_signature %}
5179
{% filter format_attribute(attribute, config.line_length, crossrefs=config.signature_crossrefs) %}
5280
{{ attribute.name }}
@@ -70,7 +98,17 @@
7098

7199
<div class="doc doc-contents {% if root %}first{% endif %}">
72100
{% block contents scoped %}
101+
{#- Contents block.
102+
103+
This block renders the contents of the attribute.
104+
It contains other blocks that users can override.
105+
Overriding the contents block allows to rearrange the order of the blocks.
106+
-#}
73107
{% block docstring scoped %}
108+
{#- Docstring block.
109+
110+
This block renders the docstring for the attribute.
111+
-#}
74112
{% with docstring_sections = attribute.docstring.parsed %}
75113
{% include "docstring"|get_template with context %}
76114
{% endwith %}

‎src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,21 @@
1+
{#- Template for members (children) of an object.
2+
3+
This template iterates on members of a given object and renders them.
4+
It can group members by category (attributes, classes, functions, modules) or render them in a flat list.
5+
6+
Context:
7+
obj (griffe.dataclasses.Object): The object to render.
8+
config (dict): The configuration options.
9+
root_members (bool): Whether the object is the root object.
10+
heading_level (int): The HTML heading level to use.
11+
-#}
12+
113
{% if obj.members %}
214
{% block logs scoped %}
15+
{#- Logging block.
16+
17+
This block can be used to log debug messages, deprecation messages, warnings, etc.
18+
-#}
319
{{ log.debug("Rendering children of " + obj.path) }}
420
{% endblock logs %}
521

‎src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja

Lines changed: 49 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,19 @@
1+
{#- Template for Python classes.
2+
3+
This template renders a Python class.
4+
5+
Context:
6+
class (griffe.dataclasses.Class): The class to render.
7+
root (bool): Whether this is the root object, injected with `:::` in a Markdown page.
8+
heading_level (int): The HTML heading level to use.
9+
config (dict): The configuration options.
10+
-#}
11+
112
{% block logs scoped %}
13+
{#- Logging block.
14+
15+
This block can be used to log debug messages, deprecation messages, warnings, etc.
16+
-#}
217
{{ log.debug("Rendering " + class.path) }}
318
{% endblock logs %}
419

@@ -27,6 +42,10 @@
2742
) %}
2843

2944
{% block heading scoped %}
45+
{#- Heading block.
46+
47+
This block renders the heading for the class.
48+
-#}
3049
{% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>{% endif %}
3150
{% if config.separate_signature %}
3251
<span class="doc doc-object-name doc-class-name">{{ class_name }}</span>
@@ -42,6 +61,10 @@
4261
{% endblock heading %}
4362

4463
{% block labels scoped %}
64+
{#- Labels block.
65+
66+
This block renders the labels for the class.
67+
-#}
4568
{% with labels = class.labels %}
4669
{% include "labels"|get_template with context %}
4770
{% endwith %}
@@ -50,6 +73,10 @@
5073
{% endfilter %}
5174

5275
{% block signature scoped %}
76+
{#- Signature block.
77+
78+
This block renders the signature for the class.
79+
-#}
5380
{% if config.separate_signature and config.merge_init_into_class %}
5481
{% if "__init__" in class.all_members %}
5582
{% with function = class.all_members["__init__"] %}
@@ -76,7 +103,17 @@
76103

77104
<div class="doc doc-contents {% if root %}first{% endif %}">
78105
{% block contents scoped %}
106+
{#- Contents block.
107+
108+
This block renders the contents of the class.
109+
It contains other blocks that users can override.
110+
Overriding the contents block allows to rearrange the order of the blocks.
111+
-#}
79112
{% block bases scoped %}
113+
{#- Class bases block.
114+
115+
This block renders the bases for the class.
116+
-#}
80117
{% if config.show_bases and class.bases %}
81118
<p class="doc doc-class-bases">
82119
Bases: {% for expression in class.bases -%}
@@ -87,6 +124,10 @@
87124
{% endblock bases %}
88125

89126
{% block docstring scoped %}
127+
{#- Docstring block.
128+
129+
This block renders the docstring for the class.
130+
-#}
90131
{% with docstring_sections = class.docstring.parsed %}
91132
{% include "docstring"|get_template with context %}
92133
{% endwith %}
@@ -100,6 +141,10 @@
100141
{% endblock docstring %}
101142

102143
{% block source scoped %}
144+
{#- Source block.
145+
146+
This block renders the source code for the class.
147+
-#}
103148
{% if config.show_source %}
104149
{% if config.merge_init_into_class %}
105150
{% if "__init__" in class.all_members and class.all_members["__init__"].source %}
@@ -132,6 +177,10 @@
132177
{% endblock source %}
133178

134179
{% block children scoped %}
180+
{#- Children block.
181+
182+
This block renders the children (members) of the class.
183+
-#}
135184
{% set root = False %}
136185
{% set heading_level = heading_level + 1 %}
137186
{% include "children"|get_template with context %}
@@ -140,5 +189,4 @@
140189
</div>
141190

142191
{% endwith %}
143-
144192
</div>

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,22 @@
1+
{#- Template for docstrings.
2+
3+
This template renders Python docstrings.
4+
Griffe parses docstrings into a list of sections, each with a `kind` and a `value`.
5+
This template can then iterate on these sections and render them according to the configuration.
6+
7+
Context:
8+
docstring_sections (list[griffe.docstrings.dataclasses.DocstringSection]): The list of docstring sections.
9+
config (dict): The configuration dictionary.
10+
heading_level (int): The heading level to use for Markdown conversion.
11+
html_id (str): The HTML ID to use for Markdown conversion.
12+
-#}
13+
114
{% if docstring_sections %}
215
{% block logs scoped %}
16+
{#- Logging block.
17+
18+
This block can be used to log debug messages, deprecation messages, warnings, etc.
19+
-#}
320
{{ log.debug("Rendering docstring") }}
421
{% endblock logs %}
522
{% for section in docstring_sections %}

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html.jinja

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,20 @@
1+
{#- Template for admonitions in docstrings.
2+
3+
This template renders admonitions using the `details` HTML element.
4+
5+
Context:
6+
section (griffe.docstrings.dataclasses.DocstringSectionAdmonition): The section to render.
7+
-#}
8+
19
{% block logs scoped %}
10+
{#- Logging block.
11+
12+
This block can be used to log debug messages, deprecation messages, warnings, etc.
13+
-#}
214
{{ log.debug("Rendering admonition") }}
315
{% endblock logs %}
16+
417
<details class="{{ section.value.kind }}" open>
518
<summary>{{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True) }}</summary>
619
{{ section.value.contents|convert_markdown(heading_level, html_id) }}
7-
</details>
20+
</details>

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,26 @@
1+
{#- Template for "Attributes" sections in docstrings.
2+
3+
This template renders a list of documented attributes in the format
4+
specified with the [`docstring_section_style`][] configuration option.
5+
6+
Context:
7+
section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
8+
-#}
9+
110
{% block logs scoped %}
11+
{#- Logging block.
12+
13+
This block can be used to log debug messages, deprecation messages, warnings, etc.
14+
-#}
215
{{ log.debug("Rendering attributes section") }}
316
{% endblock logs %}
417

518
{% import "language"|get_template as lang with context %}
19+
{#- Language module providing the `t` translation method. -#}
620

721
{% if config.docstring_section_style == "table" %}
822
{% block table_style scoped %}
23+
{#- Block for the `table` section style. -#}
924
<p><span class="doc-section-title">{{ section.title or lang.t("Attributes:") }}</span></p>
1025
<table>
1126
<thead>
@@ -38,6 +53,7 @@
3853
{% endblock table_style %}
3954
{% elif config.docstring_section_style == "list" %}
4055
{% block list_style scoped %}
56+
{#- Block for the `list` section style. -#}
4157
<p><span class="doc-section-title">{{ section.title or lang.t("Attributes:") }}</span></p>
4258
<ul>
4359
{% for attribute in section.value %}
@@ -58,6 +74,7 @@
5874
{% endblock list_style %}
5975
{% elif config.docstring_section_style == "spacy" %}
6076
{% block spacy_style scoped %}
77+
{#- Block for the `spacy` section style. -#}
6178
<table>
6279
<thead>
6380
<tr>

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,26 @@
1+
{#- Template for "Classes" sections in docstrings.
2+
3+
This template renders a list of documented classes in the format
4+
specified with the [`docstring_section_style`][] configuration option.
5+
6+
Context:
7+
section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
8+
-#}
9+
110
{% block logs scoped %}
11+
{#- Logging block.
12+
13+
This block can be used to log debug messages, deprecation messages, warnings, etc.
14+
-#}
215
{{ log.debug("Rendering classes section") }}
316
{% endblock logs %}
417

518
{% import "language"|get_template as lang with context %}
19+
{#- Language module providing the `t` translation method. -#}
620

721
{% if config.docstring_section_style == "table" %}
822
{% block table_style scoped %}
23+
{#- Block for the `table` section style. -#}
924
<p><span class="doc-section-title">{{ section.title or lang.t("Classes:") }}</span></p>
1025
<table>
1126
<thead>
@@ -30,6 +45,7 @@
3045
{% endblock table_style %}
3146
{% elif config.docstring_section_style == "list" %}
3247
{% block list_style scoped %}
48+
{#- Block for the `list` section style. -#}
3349
<p><span class="doc-section-title">{{ section.title or lang.t("Classes:") }}</span></p>
3450
<ul>
3551
{% for class in section.value %}
@@ -45,6 +61,7 @@
4561
{% endblock list_style %}
4662
{% elif config.docstring_section_style == "spacy" %}
4763
{% block spacy_style scoped %}
64+
{#- Block for the `spacy` section style. -#}
4865
<table>
4966
<thead>
5067
<tr>

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,22 @@
1+
{#- Template for "Examples" sections in docstrings.
2+
3+
This template renders a list of documented examples.
4+
It alternates between rendering text and code examples.
5+
6+
Context:
7+
section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render.
8+
-#}
9+
110
{% block logs scoped %}
11+
{#- Logging block.
12+
13+
This block can be used to log debug messages, deprecation messages, warnings, etc.
14+
-#}
215
{{ log.debug("Rendering examples section") }}
316
{% endblock logs %}
417

518
{% import "language"|get_template as lang with context %}
19+
{#- Language module providing the `t` translation method. -#}
620

721
<p><span class="doc-section-title">{{ section.title or lang.t("Examples:") }}</span></p>
822
{% for section_type, sub_section in section.value %}

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy