From 6df2dccd403a2f0aa1d283ff09a83476002b6387 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 28 Apr 2024 20:50:43 +0200 Subject: [PATCH] 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 %}{% endif %} {% if config.separate_signature %} {{ attribute_name }} @@ -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:
{% 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 %}{% endif %} {% if config.separate_signature %} {{ class_name }} @@ -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:
{% 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 %}

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:

{% endwith %} -
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. -#}
{% 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 %}{% endif %} {% if config.separate_signature %} {{ function_name }} @@ -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 @@
{% 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 %}
{{ lang.t("Source code in") }} 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 %}{% endif %} {% if config.separate_signature %} {{ module_name }} @@ -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 @@
{% 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.