From cb5420ec3b4e7d2daab169303933dee7e23118ed Mon Sep 17 00:00:00 2001 From: huohong <346479823@qq.com> Date: Fri, 14 Feb 2025 18:13:38 +0800 Subject: [PATCH] support function name show as docstring summary --- test/mkdocs.yml | 25 +++ test/templates/python/material/function.html | 11 ++ .../python/material/function.html.jinja | 154 ++++++++++++++++++ 3 files changed, 190 insertions(+) create mode 100644 test/mkdocs.yml create mode 100644 test/templates/python/material/function.html create mode 100644 test/templates/python/material/function.html.jinja diff --git a/test/mkdocs.yml b/test/mkdocs.yml new file mode 100644 index 0000000000..f9befa59e2 --- /dev/null +++ b/test/mkdocs.yml @@ -0,0 +1,25 @@ +site_name: TDengine Case List +docs_dir: case_list_docs +theme: + name: "material" + +markdown_extensions: +- attr_list +- toc: + permalink: true + separator: "-" + baselevel: 1 + toc_depth: 4 +plugins: +- search +- mkdocstrings: + custom_templates: templates + handlers: + python: + options: + heading_level: 2 + show_root_heading: true + show_bases: false + show_source: false + show_object_full_path: false + filters: [ "^test_", "TDTestCase" ] diff --git a/test/templates/python/material/function.html b/test/templates/python/material/function.html new file mode 100644 index 0000000000..d3a9dbb193 --- /dev/null +++ b/test/templates/python/material/function.html @@ -0,0 +1,11 @@ +{% extends "function.html.jinja" %} + +{% block logs scoped %} + {{ super() }} + {# TODO: Switch to a warning after some time. #} + {{ log.info( + "DeprecationWarning: Extending '_base/function.html' is deprecated, extend '_base/function.html.jinja' instead. " ~ + "After some time, this message will be logged as a warning, causing strict builds to fail.", + once=True, + ) }} +{% endblock logs %} \ No newline at end of file diff --git a/test/templates/python/material/function.html.jinja b/test/templates/python/material/function.html.jinja new file mode 100644 index 0000000000..1146007823 --- /dev/null +++ b/test/templates/python/material/function.html.jinja @@ -0,0 +1,154 @@ +{#- 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. -#} + +
+ {% 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. -#} + + {% if not root or config.show_root_heading %} + {% filter heading( + heading_level, + role="function", + id=html_id, + class="doc doc-heading", + toc_label=((' ')|safe if config.show_symbol_type_toc else '') + function.docstring.value.split("\n", 1)[0] if function.docstring.value.split("\n", 1)[0] else function.name, + ) %} + + {% block heading scoped %} + {#- Heading block. + + This block renders the heading for the function. + -#} + {% if config.show_symbol_type_heading %}{% endif %} + {% if config.separate_signature %} + {{ config.heading if config.heading and root else function_name }} + {% else %} + {%+ filter highlight(language="python", inline=True) %} + {{ function_name }}{% include "signature"|get_template with context %} + {% endfilter %} + {% endif %} + {% 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 %} + {% endblock labels %} + + {% endfilter %} + + {% block signature scoped %} + {#- Signature block. + + This block renders the signature for the function, + as well as its overloaded signatures if any. + -#} + {% if function.overloads %} +
+ {% for overload in function.overloads %} + {% filter format_signature(overload, config.line_length, annotations=True, crossrefs=config.signature_crossrefs) %} + {{ overload.name }} + {% endfilter %} + {% endfor %} +
+ {% endif %} + {% if config.separate_signature %} + {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %} + {{ function.name }} + {% endfilter %} + {% endif %} + {% endblock signature %} + + {% else %} + + {% if config.show_root_toc_entry %} + {% filter heading( + heading_level, + role="function", + id=html_id, + toc_label=((' ')|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else function.name), + hidden=True, + ) %} + {% endfilter %} + {% endif %} + {% set heading_level = heading_level - 1 %} + {% 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 %} +
+ {{ lang.t("Source code in") }} + {%- if function.relative_filepath.is_absolute() -%} + {{ function.relative_package_filepath }} + {%- else -%} + {{ function.relative_filepath }} + {%- endif -%} + + {{ function.source|highlight(language="python", linestart=function.lineno or 0, linenums=True) }} +
+ {% endif %} + {% endblock source %} + {% endblock contents %} +
+ + {% endwith %} +