TDengine/test/templates/python/material/function.html.jinja

{#- Template for Python functions.

  This template renders a Python function or method.
  
  Context:
    function (griffe.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 %}
  
      {% if root %}
        {% set show_full_path = config.show_root_full_path %}
        {% set root_members = True %}
      {% elif root_members %}
        {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
        {% set root_members = False %}
      {% else %}
        {% set show_full_path = config.show_object_full_path %}
      {% 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. -#}

      {# Check if docstring contains "skip" in Labels line #}
      {% set has_skip_label = namespace(value=false) %}
      {% if function.docstring and function.docstring.value %}
        {% for line in function.docstring.value.split("\n") %}
          {% if line.strip().startswith("Labels:") %}
            {# Extract labels and check if "skip" is one of them #}
            {% set labels_text = line.replace("Labels:", "").strip() %}
            {% set labels = labels_text.split(",") %}
            {% for label in labels %}
              {% if label.strip().lower() == "skip" %}
                {% set has_skip_label.value = true %}
              {% endif %}
            {% endfor %}
          {% endif %}
        {% endfor %}
      {% endif %}
  
      {% if "cases/" in function.relative_filepath|string %}
        {# Only generate docstring for methods starting with "test_" or "Test" in the "cases" directory, and not labeled as skip #}
        {% if (function.name.startswith("test_") or function.name.startswith("Test")) and not has_skip_label.value %}
          {% set should_render = true %}
        {% else %}
          {% set should_render = false %}
        {% endif %}
      {% else %}
        {# For other directories, generate docstring for all methods unless labeled as skip #}
        {% set should_render = not has_skip_label.value %}
      {% endif %}
  
      {% if should_render %}
        {% filter heading(
            heading_level,
            role="function",
            id=html_id,
            class="doc doc-heading",
            toc_label=(('<code class="doc-symbol doc-symbol-toc doc-symbol-' + symbol_type + '"></code>&nbsp;')|safe if config.show_symbol_type_toc else '') + 
                      (
                        function.docstring.value.split("\n", 1)[0] if "cases/" in function.relative_filepath|string and function.docstring.value else
                        function.name
                      ),
          ) %}

          {% block heading scoped %}
            {#- Heading block.

            This block renders the heading for the function.
            -#}
            {% if not ("cases/" in function.relative_filepath|string and function.docstring.value) %}
              {% if config.separate_signature %}
                <span class="doc doc-object-name doc-function-name">{{ config.heading if config.heading and root else function_name }}</span>
              {% else %}
                  {{ function_name }}{% include "signature"|get_template with context %}
              {% endif %}
            {% endif %}
          {% endblock heading %}

        {% endfilter %}
  
        <div class="doc doc-contents {% if root %}first{% endif %}">
          {% block contents scoped %}
            {# 渲染 docstring #}
            {% block docstring scoped %}
              {% if not ("cases/" in function.relative_filepath|string and function.docstring.value) %}
                {% with docstring_sections = function.docstring.parsed %}
                  {% include "docstring"|get_template with context %}
                {% endwith %}
              {% else %}
                {% with docstring_lines = function.docstring.value.split("\n") %}
                  {% set summary = docstring_lines[0] if docstring_lines else "" %}
                  {% set stop_keywords = ["Catalog:", "Since:", "Labels:", "Jira:", "History:"] %}
                  {% set details = [] %}
                  {% with ns = namespace(stop=false) %}
                    {% for line in docstring_lines[2:] %}
                      {% if not ns.stop %}
                        {% for kw in stop_keywords %}
                          {% if line.strip().startswith(kw) %}
                            {% set ns.stop = true %}
                          {% endif %}
                        {% endfor %}
                        {% if not ns.stop %}
                          {% set _ = details.append(line) %}
                        {% endif %}
                      {% endif %}
                    {% endfor %}
                  {% endwith %}

                  <div class="doc doc-docstring doc-summary">
                    <strong>Summary:</strong> {{ summary|safe }}
                  </div>
                  {% if details %}
                    <div class="doc doc-docstring doc-description">
                      <strong>Description:</strong>
                      <div style="background: #f8f8f8; border-radius: 4px; padding: 0.8em 1em; margin: 0.5em 0; font-size: 1em;">
                        {% for line in details %}
                          {% set indent = (line|length - line.lstrip()|length) %}
                          <div style="margin-left: {{ indent * 0.8 }}em; white-space: pre-wrap;">{{ line }}</div>
                        {% endfor %}
                      </div>
                    </div>
                  {% endif %}
                  <div class="doc doc-docstring doc-function.path">
                    <strong>Path:</strong>
                    <a href="https://github.com/taosdata/TDengine/blob/{{ config.github_branch }}/test/{{ function.relative_filepath }}" target="_blank">
                      {{ function.relative_filepath|safe }}
                    </a>
                  </div>
                {% endwith %}
              {% endif %}
            {% endblock docstring %}
          {% endblock contents %}
        </div>

      {% endif %}
    {% endwith %}
  </div>