From 583b8fefd987ccaa37a016121427e1141827ff71 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= <dev@pawamoy.fr> Date: Mon, 29 Apr 2024 12:00:49 +0200 Subject: [PATCH] docs: Document Jinja templates Issue-149: https://github.com/mkdocstrings/python/issues/149 PR-156: https://github.com/mkdocstrings/python/pull/156 --- .../material/_base/attribute.html.jinja | 38 ++++++++++++++ .../material/_base/children.html.jinja | 16 ++++++ .../templates/material/_base/class.html.jinja | 50 ++++++++++++++++++- .../material/_base/docstring.html.jinja | 17 +++++++ .../_base/docstring/admonition.html.jinja | 15 +++++- .../_base/docstring/attributes.html.jinja | 17 +++++++ .../_base/docstring/classes.html.jinja | 17 +++++++ .../_base/docstring/examples.html.jinja | 14 ++++++ .../_base/docstring/functions.html.jinja | 17 +++++++ .../_base/docstring/modules.html.jinja | 17 +++++++ .../docstring/other_parameters.html.jinja | 17 +++++++ .../_base/docstring/parameters.html.jinja | 17 +++++++ .../_base/docstring/raises.html.jinja | 17 +++++++ .../_base/docstring/receives.html.jinja | 17 +++++++ .../_base/docstring/returns.html.jinja | 17 +++++++ .../material/_base/docstring/warns.html.jinja | 17 +++++++ .../_base/docstring/yields.html.jinja | 17 +++++++ .../material/_base/expression.html.jinja | 30 +++++++++++ .../material/_base/function.html.jinja | 44 ++++++++++++++++ .../material/_base/labels.html.jinja | 15 ++++++ .../material/_base/language.html.jinja | 8 ++- .../material/_base/languages/en.html.jinja | 10 +++- .../material/_base/languages/ja.html.jinja | 10 +++- .../material/_base/languages/zh.html.jinja | 10 +++- .../material/_base/module.html.jinja | 37 ++++++++++++++ .../material/_base/signature.html.jinja | 26 +++++++++- .../material/_base/summary.html.jinja | 6 +++ .../_base/summary/attributes.html.jinja | 6 +++ .../material/_base/summary/classes.html.jinja | 6 +++ .../_base/summary/functions.html.jinja | 6 +++ .../material/_base/summary/modules.html.jinja | 6 +++ .../_base/docstring/attributes.html.jinja | 14 ++++++ .../docstring/other_parameters.html.jinja | 14 ++++++ .../_base/docstring/parameters.html.jinja | 14 ++++++ .../_base/docstring/raises.html.jinja | 14 ++++++ .../_base/docstring/receives.html.jinja | 14 ++++++ .../_base/docstring/returns.html.jinja | 14 ++++++ .../_base/docstring/warns.html.jinja | 14 ++++++ .../_base/docstring/yields.html.jinja | 14 ++++++ .../readthedocs/_base/language.html.jinja | 10 +++- 40 files changed, 666 insertions(+), 13 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 fd537034..11bc4e77 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja +++ b/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 %} 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 b63b9a6a..b0ec4007 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja +++ b/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 %} 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 2bfa2bf0..bb32a91c 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja +++ b/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> 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 8477dc0a..f5095eb4 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja +++ b/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 %} 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 b5053342..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 @@ -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> \ No newline at end of file +</details> 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 d1bb3bb0..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 @@ -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> 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 60ec7e54..1aee5fd2 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 @@ -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> 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 1e79a53a..48913f80 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 @@ -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 %} 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 35197c80..53bda233 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 @@ -1,11 +1,26 @@ +{#- 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 %} +{#- 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("Methods:") if obj.is_class else lang.t("Functions:") }}</span></p> <table> <thead> @@ -32,6 +47,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 +65,7 @@ {% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style scoped %} + {#- Block for the `spacy` section style. -#} <table> <thead> <tr> 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 fc212db9..239f7a55 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 @@ -1,11 +1,26 @@ +{#- 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 %} +{#- 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("Modules:") }}</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("Modules:") }}</span></p> <ul> {% for module 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> 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 c3d4af97..7daabeda 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 @@ -1,11 +1,26 @@ +{#- 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 %} +{#- 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("Other Parameters:") }}</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("Other Parameters:") }}</span></p> <ul> {% for parameter 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> 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 f411e114..3de6f4a9 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 @@ -1,11 +1,26 @@ +{#- 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 %} +{#- 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("Parameters:") }}</span></p> <table> <thead> @@ -48,6 +63,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 +89,7 @@ {% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style scoped %} + {#- Block for the `spacy` section style. -#} <table> <thead> <tr> 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 12ff1496..79024057 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 @@ -1,11 +1,26 @@ +{#- Template for "Raises" sections in docstrings. + +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. +-#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {{ log.debug("Rendering raises 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("Raises:") }}</span></p> <table> <thead> @@ -36,6 +51,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">{{ lang.t(section.title) or lang.t("Raises:") }}</span></p> <ul> {% for raises in section.value %} @@ -55,6 +71,7 @@ {% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style scoped %} + {#- Block for the `spacy` section style. -#} <table> <thead> <tr> 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 13e0ea30..2fcce8ef 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 @@ -1,11 +1,26 @@ +{#- Template for "Receives" sections in docstrings. + +This template renders a list of documented received values (generators) 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 receives 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. -#} {% set name_column = section.value|selectattr("name")|any %} <p><span class="doc-section-title">{{ section.title or lang.t("Receives:") }}</span></p> <table> @@ -39,6 +54,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("Receives:") }}</span></p> <ul> {% for receives in section.value %} @@ -61,6 +77,7 @@ {% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style scoped %} + {#- Block for the `spacy` section style. -#} <table> <thead> <tr> 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 9a330780..8feeb054 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 @@ -1,11 +1,26 @@ +{#- Template for "Returns" sections in docstrings. + +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. +-#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {{ log.debug("Rendering returns 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. -#} {% set name_column = section.value|selectattr("name")|any %} <p><span class="doc-section-title">{{ section.title or lang.t("Returns:") }}</span></p> <table> @@ -39,6 +54,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("Returns:") }}</span></p> <ul> {% for returns in section.value %} @@ -61,6 +77,7 @@ {% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style scoped %} + {#- Block for the `spacy` section style. -#} <table> <thead> <tr> 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 b8ed3851..6143257d 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 @@ -1,11 +1,26 @@ +{#- Template for "Warns" sections in docstrings. + +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. +-#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {{ log.debug("Rendering warns 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("Warns:") }}</span></p> <table> <thead> @@ -36,6 +51,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("Warns:") }}</span></p> <ul> {% for warns in section.value %} @@ -55,6 +71,7 @@ {% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style scoped %} + {#- Block for the `spacy` section style. -#} <table> <thead> <tr> 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 6172a254..d326c1fe 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 @@ -1,11 +1,26 @@ +{#- Template for "Yields" sections in docstrings. + +This template renders a list of documented yielded values (generators) 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 yields 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. -#} {% set name_column = section.value|selectattr("name")|any %} <p><span class="doc-section-title">{{ section.title or lang.t("Yields:") }}</span></p> <table> @@ -39,6 +54,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("Yields:") }}</span></p> <ul> {% for yields in section.value %} @@ -61,6 +77,7 @@ {% endblock list_style %} {% elif config.docstring_section_style == "spacy" %} {% block spacy_style scoped %} + {#- Block for the `spacy` section style. -#} <table> <thead> <tr> 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 c219f636..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,7 +1,28 @@ +{#- Template for expressions. + +This template renders a Griffe expression, +which is a tree-like structure representing a Python expression. +-#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {% 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 -%} @@ -24,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 c4d0f1fc..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,8 +1,24 @@ +{#- 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. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {{ log.debug("Rendering " + function.path) }} {% endblock logs %} {% import "language"|get_template as lang with context %} +{#- Language module providing the `t` translation method. -#} <div class="doc doc-object doc-function"> {% with obj = function, html_id = function.path %} @@ -18,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( @@ -30,6 +48,10 @@ ) %} {% block heading scoped %} + {#- Heading block. + + This block renders the heading for the function. + -#} {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-{{ symbol_type }}"></code>{% endif %} {% if config.separate_signature %} <span class="doc doc-object-name doc-function-name">{{ function_name }}</span> @@ -41,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 %} @@ -49,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 }} @@ -73,13 +103,27 @@ <div class="doc doc-contents {% if root %}first{% endif %}"> {% 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 %} <details class="quote"> <summary>{{ lang.t("Source code in") }} <code> 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 bcdc112b..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,5 +1,20 @@ +{#- 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. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {{ log.debug("Rendering labels") }} {% endblock logs %} <span class="doc doc-labels"> diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja index dd3fe800..5b643726 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja @@ -1,6 +1,12 @@ +{#- Import translation macros for the given language and fallback language. -#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {% endblock logs %} -<!-- Import translations for given language and fallback --> + {% set lang_pth = "languages/" ~ locale | get_template %} {% if lang_pth is existing_template %} {% import lang_pth as lang %} 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 5a771d30..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,6 +1,12 @@ -<!-- Translations: English --> +{#- Macro for English translations. -#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {% endblock logs %} + {% macro t(key) %}{{ { "ATTRIBUTE": "ATTRIBUTE", "Attributes:": "Attributes:", @@ -36,4 +42,4 @@ "Warns:": "Warns:", "YIELDS": "YIELDS", "Yields:": "Yields:", -}[key] }}{% endmacro %} \ No newline at end of file +}[key] }}{% endmacro %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja index 748fd8b7..a6b7728b 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja @@ -1,6 +1,12 @@ -<!-- Translations: Japanese --> +{#- Macro for Japanese translations. -#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {% endblock logs %} + {% macro t(key) %}{{ { "ATTRIBUTE": "属性", "Attributes:": "属性:", @@ -36,4 +42,4 @@ "Warns:": "警告:", "YIELDS": "返す", "Yields:": "返す:", -}[key] }}{% endmacro %} \ No newline at end of file +}[key] }}{% endmacro %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja index 772e33cd..f748b83c 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja @@ -1,6 +1,12 @@ -<!-- Translations: Chinese --> +{#- Macro for Chinese translations. -#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {% endblock logs %} + {% macro t(key) %}{{ { "ATTRIBUTE": "属性", "Attributes:": "属性:", @@ -36,4 +42,4 @@ "WARNS": "警告", "YIELDS": "产生", "Yields:": "产生:", -}[key] }}{% endmacro %} \ No newline at end of file +}[key] }}{% endmacro %} 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 02665e20..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,4 +1,19 @@ +{#- 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. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {{ log.debug("Rendering " + module.path) }} {% endblock logs %} @@ -27,6 +42,10 @@ ) %} {% block heading scoped %} + {#- Heading block. + + This block renders the heading for the module. + -#} {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-module"></code>{% endif %} {% if config.separate_signature %} <span class="doc doc-object-name doc-module-name">{{ module_name }}</span> @@ -36,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 %} @@ -58,13 +81,27 @@ <div class="doc doc-contents {% if root %}first{% endif %}"> {% 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 d5bd4220..2d87986c 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja @@ -1,7 +1,22 @@ +{#- 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 %} + {%- block logs scoped -%} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {{ log.debug("Rendering signature") }} - {% endblock logs %} + {%- endblock logs -%} {%- with -%} {%- set ns = namespace( @@ -16,6 +31,7 @@ {%- for parameter in function.parameters -%} {%- if parameter.name not in ("self", "cls") or loop.index0 > 0 or not (function.parent and function.parent.is_class) -%} + {#- Handle parameter kind. -#} {%- if parameter.kind.value == "positional-only" -%} {%- set ns.has_pos_only = True -%} {%- else -%} @@ -27,6 +43,7 @@ {%- endif -%} {%- endif -%} + {#- Prepare type annotation. -#} {%- if config.show_signature_annotations and parameter.annotation is not none -%} {%- set ns.equal = " = " -%} {%- if config.separate_signature and config.signature_crossrefs -%} @@ -41,14 +58,17 @@ {%- set ns.annotation = "" -%} {%- endif -%} + {#- Prepare default value. -#} {%- if parameter.default is not none and parameter.kind.value != "variadic positional" and parameter.kind.value != "variadic keyword" -%} {%- set default = ns.equal + parameter.default|safe -%} {%- endif -%} + {#- TODO: Move inside kind handling above? -#} {%- if parameter.kind.value == "variadic positional" -%} {%- set ns.render_kw_only_separator = False -%} {%- endif -%} + {#- Render name, annotation and default. -#} {% if parameter.kind.value == "variadic positional" %}*{% elif parameter.kind.value == "variadic keyword" %}**{% endif -%} {{ parameter.name }}{{ ns.annotation }}{{ default }} {%- if not loop.last %}, {% endif -%} @@ -56,6 +76,8 @@ {%- endif -%} {%- endfor -%} ) + + {#- Render return type. -#} {%- if config.show_signature_annotations and function.annotation and not (config.merge_init_into_class and function.name == "__init__" ) 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 2390659d..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,2 +1,8 @@ +{#- Template for auto-summaries. -#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {% endblock logs %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary/attributes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/summary/attributes.html.jinja index 2390659d..cb966fb1 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/summary/attributes.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary/attributes.html.jinja @@ -1,2 +1,8 @@ +{#- Summary of attributes. -#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {% endblock logs %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary/classes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/summary/classes.html.jinja index 2390659d..94456775 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/summary/classes.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary/classes.html.jinja @@ -1,2 +1,8 @@ +{#- Summary of classes. -#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {% endblock logs %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary/functions.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/summary/functions.html.jinja index 2390659d..5e8305aa 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/summary/functions.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary/functions.html.jinja @@ -1,2 +1,8 @@ +{#- Summary of functions/methods. -#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {% endblock logs %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary/modules.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/summary/modules.html.jinja index 2390659d..04387b32 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/summary/modules.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary/modules.html.jinja @@ -1,2 +1,8 @@ +{#- Summary of modules. -#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {% endblock logs %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja index c3586f6a..8df20e1c 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja @@ -1,8 +1,22 @@ +{#- 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() }} {% endblock %} {% import "language"|get_template as lang with context %} +{#- Language module providing the `t` translation method. -#} <table class="field-list"> <colgroup> diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html.jinja index 339a0cee..4b416b65 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html.jinja @@ -1,8 +1,22 @@ +{#- 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() }} {% endblock %} {% import "language"|get_template as lang with context %} +{#- Language module providing the `t` translation method. -#} <table class="field-list"> <colgroup> diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja index ad69e78a..10bbd7ba 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja @@ -1,8 +1,22 @@ +{#- 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() }} {% endblock %} {% import "language"|get_template as lang with context %} +{#- Language module providing the `t` translation method. -#} <table class="field-list"> <colgroup> diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja index ae7f38dc..f350bc97 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja @@ -1,8 +1,22 @@ +{#- Template for "Raises" sections in docstrings. + +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. +-#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {{ log.debug() }} {% endblock %} {% import "language"|get_template as lang with context %} +{#- Language module providing the `t` translation method. -#} <table class="field-list"> <colgroup> diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja index a37db154..804a04a0 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja @@ -1,8 +1,22 @@ +{#- Template for "Receives" sections in docstrings. + +This template renders a list of documented received values (generators) 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() }} {% endblock %} {% import "language"|get_template as lang with context %} +{#- Language module providing the `t` translation method. -#} <table class="field-list"> <colgroup> diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja index 8f7dbd9b..0074327a 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja @@ -1,8 +1,22 @@ +{#- Template for "Returns" sections in docstrings. + +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. +-#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {{ log.debug() }} {% endblock %} {% import "language"|get_template as lang with context %} +{#- Language module providing the `t` translation method. -#} <table class="field-list"> <colgroup> diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja index 8ae5eb17..88308b68 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja @@ -1,8 +1,22 @@ +{#- Template for "Warns" sections in docstrings. + +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. +-#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {{ log.debug() }} {% endblock %} {% import "language"|get_template as lang with context %} +{#- Language module providing the `t` translation method. -#} <table class="field-list"> <colgroup> diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja index 44670856..bd43955d 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja @@ -1,8 +1,22 @@ +{#- Template for "Yields" sections in docstrings. + +This template renders a list of documented yielded values (generators) 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() }} {% endblock %} {% import "language"|get_template as lang with context %} +{#- Language module providing the `t` translation method. -#} <table class="field-list"> <colgroup> diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html.jinja index 9c03b815..5b643726 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html.jinja @@ -1,6 +1,12 @@ +{#- Import translation macros for the given language and fallback language. -#} + {% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} {% endblock logs %} -<!-- Import translations for given language and fallback --> + {% set lang_pth = "languages/" ~ locale | get_template %} {% if lang_pth is existing_template %} {% import lang_pth as lang %} @@ -9,4 +15,4 @@ {% else %} {% import "languages/en"|get_template as lang %} {% macro t(key) %}{{ lang.t(key) }}{% endmacro %} -{% endif %} \ No newline at end of file +{% endif %}