From f2122d7fa119ed055ffe2b2bac72d2c643daca1c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 13 Feb 2022 14:39:35 +0100 Subject: [PATCH 1/8] refactor: Use more explicit template debug messages --- .../python/templates/material/_base/attribute.html | 2 +- .../python/templates/material/_base/children.html | 2 +- .../python/templates/material/_base/class.html | 2 +- .../python/templates/material/_base/docstring.html | 2 +- .../python/templates/material/_base/docstring/admonition.html | 2 +- .../python/templates/material/_base/docstring/attributes.html | 2 +- .../python/templates/material/_base/docstring/examples.html | 2 +- .../templates/material/_base/docstring/other_parameters.html | 2 +- .../python/templates/material/_base/docstring/parameters.html | 2 +- .../python/templates/material/_base/docstring/raises.html | 2 +- .../python/templates/material/_base/docstring/receives.html | 2 +- .../python/templates/material/_base/docstring/returns.html | 2 +- .../python/templates/material/_base/docstring/warns.html | 2 +- .../python/templates/material/_base/docstring/yields.html | 2 +- .../python/templates/material/_base/function.html | 2 +- .../python/templates/material/_base/module.html | 2 +- .../python/templates/material/_base/signature.html | 2 +- 17 files changed, 17 insertions(+), 17 deletions(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html index 31066fc8..ad1a39d5 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering " + attribute.path) }} {% if config.show_if_no_docstring or attribute.has_docstrings %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/children.html b/src/mkdocstrings_handlers/python/templates/material/_base/children.html index 5cf217f5..fe9a194d 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/children.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/children.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering children of " + obj.path) }} {% if obj.members %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html b/src/mkdocstrings_handlers/python/templates/material/_base/class.html index a5c9c879..3b72f54a 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering " + class.path) }} {% if config.show_if_no_docstring or class.has_docstrings %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html index f8071bd7..b473a8f8 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering docstring") }} {% if docstring_sections %} {% for section in docstring_sections %} {% if section.kind.value == "text" %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html index a8c08873..b3cab485 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering admonition") }}
{{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True) }} {{ section.value.contents|convert_markdown(heading_level, html_id) }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html index 13515121..5d0dc85f 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering attributes section") }} {% if config.docstring_section_style == "table" %}

{{ section.title or "Attributes:" }}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html index 553308ff..0f96e1e1 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering examples section") }}

{{ section.title or "Examples:" }}

{% for section_type, sub_section in section.value %} {% if section_type == "markdown" %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html index d31ef7fc..709a799c 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering other parameters section") }} {% if config.docstring_section_style == "table" %}

{{ section.title or "Other Parameters:" }}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html index 9bc227a5..4a28ae1c 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering parameters section") }} {% if config.docstring_section_style == "table" %}

{{ section.title or "Parameters:" }}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html index 2de94208..71d76e1f 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering raises section") }} {% if config.docstring_section_style == "table" %}

{{ section.title or "Raises:" }}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html index f6d9c821..0a6c5b5c 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering receives section") }} {% if config.docstring_section_style == "table" %} {% set name_column = section.value|selectattr("name")|any %}

{{ section.title or "Receives:" }}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html index 1c5824b3..b62c809a 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering returns section") }} {% if config.docstring_section_style == "table" %} {% set name_column = section.value|selectattr("name")|any %}

{{ section.title or "Returns:" }}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html index 7285398a..4b2d6865 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering warns section") }} {% if config.docstring_section_style == "table" %}

{{ section.title or "Warns:" }}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html index eabbedf8..b24ce805 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering yields section") }} {% if config.docstring_section_style == "table" %} {% set name_column = section.value|selectattr("name")|any %}

{{ section.title or "Yields:" }}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html b/src/mkdocstrings_handlers/python/templates/material/_base/function.html index fa190793..a17f3a22 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering " + function.path) }} {% if config.show_if_no_docstring or function.has_docstrings %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/module.html b/src/mkdocstrings_handlers/python/templates/material/_base/module.html index 998f93e8..54e4d4e4 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/module.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/module.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering " + module.path) }} {% if config.show_if_no_docstring or module.has_docstrings %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html index 10d3bb31..d0a7fbe9 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html @@ -1,4 +1,4 @@ -{{ log.debug() }} +{{ log.debug("Rendering signature of " + function.path) }} {%- if config.show_signature -%} {%- with -%} From fa0a7c0774fbd72bef6c3ea9f4e1d21e8cf24923 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 13 Feb 2022 14:40:56 +0100 Subject: [PATCH 2/8] style: Lint --- src/mkdocstrings_handlers/python/collector.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/mkdocstrings_handlers/python/collector.py b/src/mkdocstrings_handlers/python/collector.py index 42e6a371..02502e05 100644 --- a/src/mkdocstrings_handlers/python/collector.py +++ b/src/mkdocstrings_handlers/python/collector.py @@ -3,6 +3,8 @@ It collects data with [Griffe](https://github.com/pawamoy/griffe). """ +from __future__ import annotations + from collections import ChainMap from griffe.agents.extensions import load_extensions @@ -34,7 +36,7 @@ class PythonCollector(BaseCollector): fallback_config: dict = {"fallback": True} def __init__(self) -> None: - """Initialize the object.""" + """Initialize the collector.""" self._modules_collection: ModulesCollection = ModulesCollection() self._lines_collection: LinesCollection = LinesCollection() From 52919c559378a6006bbe931423c5f03eb5883eaf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 13 Feb 2022 14:41:42 +0100 Subject: [PATCH 3/8] fix: Fix rendering of labels --- .../python/templates/material/_base/labels.html | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/labels.html b/src/mkdocstrings_handlers/python/templates/material/_base/labels.html index 69a2da4c..a7e8ec38 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/labels.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/labels.html @@ -1,8 +1,8 @@ -{{ log.debug() }} -{% if properties %} +{{ log.debug("Rendering labels") }} +{% if labels %} - {% for property in properties %} - {{ property }} + {% for label in labels %} + {{ label }} {% endfor %} {% endif %} From 885696e05606d07334e0428128ed688d54098da1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 13 Feb 2022 14:42:38 +0100 Subject: [PATCH 4/8] refactor: Don't add trailing parentheses in functions heading when separate signature --- .../python/templates/material/_base/function.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html b/src/mkdocstrings_handlers/python/templates/material/_base/function.html index a17f3a22..13639f57 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html @@ -23,7 +23,7 @@ toc_label=function.name ~ "()") %} {% if config.separate_signature %} - {% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %}() + {% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %} {% else %} {% filter highlight(language="python", inline=True) %} {% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %} From ac1197062f2e23e819f144fe74a774d504d0ac49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 13 Feb 2022 14:43:03 +0100 Subject: [PATCH 5/8] fix: Restore full cross-refs paths on hover --- .../python/templates/material/_base/expression.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html index 29751104..76a50da7 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html @@ -6,5 +6,5 @@ {%- elif original_expression is string -%} {{ original_expression }} {%- else -%} - {{ original_expression.source }} + {{ original_expression.source }} {%- endif -%} From e962b885f48570762c5bfcefc9b61e5fc1df1c70 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 13 Feb 2022 14:44:07 +0100 Subject: [PATCH 6/8] feat: Support separate attribute signature --- src/mkdocstrings_handlers/python/renderer.py | 25 ++++++++++++++++--- .../templates/material/_base/attribute.html | 22 +++++++++++++--- 2 files changed, 39 insertions(+), 8 deletions(-) diff --git a/src/mkdocstrings_handlers/python/renderer.py b/src/mkdocstrings_handlers/python/renderer.py index 2f4087fd..34c994ba 100644 --- a/src/mkdocstrings_handlers/python/renderer.py +++ b/src/mkdocstrings_handlers/python/renderer.py @@ -135,8 +135,25 @@ def update_env(self, md: Markdown, config: dict) -> None: # noqa: D102 (ignore self.env.filters["crossref"] = self.do_crossref self.env.filters["multi_crossref"] = self.do_multi_crossref self.env.filters["order_members"] = self.do_order_members + self.env.filters["format_code"] = self.do_format_code self.env.filters["format_signature"] = self.do_format_signature + def do_format_code(self, code: str, line_length: int) -> str: + """Format code using Black. + + Parameters: + code: The code to format. + line_length: The line length to give to Black. + + Returns: + The same code, formatted. + """ + code = code.strip() + if len(code) < line_length: + return code + formatter = _get_black_formatter() + return formatter(code, line_length) + def do_format_signature(self, signature: str, line_length: int) -> str: """Format a signature using Black. @@ -151,7 +168,9 @@ def do_format_signature(self, signature: str, line_length: int) -> str: if len(code) < line_length: return code formatter = _get_black_formatter() - return formatter(code, line_length) + formatted = formatter(f"def {code}: pass", line_length) + # remove starting `def ` and trailing `: pass` + return formatted[4:-5].strip()[:-1] def do_order_members(self, members: Sequence[Object | Alias], order: Order) -> Sequence[Object | Alias]: """Order members given an ordering method. @@ -219,8 +238,6 @@ def _get_black_formatter(): def formatter(code, line_length): # noqa: WPS430 mode = Mode(line_length=line_length) - formatted = format_str(f"def {code}: pass", mode=mode) - # remove starting `def ` and trailing `: pass` - return formatted[4:-5].strip()[:-1] + return format_str(code, mode=mode) return formatter diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html index ad1a39d5..527c38fd 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html @@ -22,11 +22,15 @@ class="doc doc-heading", toc_label=attribute.name) %} - {% filter highlight(language="python", inline=True) %} + {% if config.separate_signature %} {% if show_full_path %}{{ attribute.path }}{% else %}{{ attribute.name }}{% endif %} - {% if attribute.annotation %}: {{ attribute.annotation }}{% endif %} - {% if attribute.value %} = {{ attribute.value }}{% endif %} - {% endfilter %} + {% else %} + {% filter highlight(language="python", inline=True) %} + {% if show_full_path %}{{ attribute.path }}{% else %}{{ attribute.name }}{% endif %} + {% if attribute.annotation %}: {{ attribute.annotation }}{% endif %} + {% if attribute.value %} = {{ attribute.value }}{% endif %} + {% endfilter %} + {% endif %} {% with labels = attribute.labels %} {% include "labels.html" with context %} @@ -34,6 +38,16 @@ {% endfilter %} + {% if config.separate_signature %} + {% filter highlight(language="python", inline=False) %} + {% filter format_code(config.line_length) %} + {% if show_full_path %}{{ attribute.path }}{% else %}{{ attribute.name }}{% endif %} + {% if attribute.annotation %}: {{ attribute.annotation|safe }}{% endif %} + {% if attribute.value %} = {{ attribute.value|safe }}{% endif %} + {% endfilter %} + {% endfilter %} + {% endif %} + {% else %} {% if config.show_root_toc_entry %} {% filter heading(heading_level, From 1b4d1c0e9254fc51756caed3875fbc8c1da079a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 13 Feb 2022 14:45:03 +0100 Subject: [PATCH 7/8] feat: Add option to merge `__init__` methods' docstrings into their classes' docstrings --- mkdocs.yml | 6 ++ src/mkdocstrings_handlers/python/renderer.py | 2 + .../templates/material/_base/children.html | 42 ++++++----- .../templates/material/_base/class.html | 70 +++++++++++++++---- .../templates/material/_base/signature.html | 38 +++++----- 5 files changed, 109 insertions(+), 49 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index c705117e..ec029ae6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -74,9 +74,15 @@ plugins: handlers: python: import: + - https://docs.python.org/3/objects.inv - https://mkdocstrings.github.io/objects.inv + selection: + docstring_style: google + docstring_options: + ignore_init_summary: yes rendering: show_submodules: no + merge_init_into_class: yes watch: - src/mkdocstrings_handlers diff --git a/src/mkdocstrings_handlers/python/renderer.py b/src/mkdocstrings_handlers/python/renderer.py index 34c994ba..77f367e4 100644 --- a/src/mkdocstrings_handlers/python/renderer.py +++ b/src/mkdocstrings_handlers/python/renderer.py @@ -73,6 +73,7 @@ class PythonRenderer(BaseRenderer): "show_signature_annotations": False, "separate_signature": False, "line_length": 60, + "merge_init_into_class": False, "show_source": True, "show_bases": True, "show_submodules": True, @@ -96,6 +97,7 @@ class PythonRenderer(BaseRenderer): **`show_signature_annotations`** | `bool` | Show the type annotations in method and function signatures. | `False` **`separate_signature`** | `bool` | Whether to put the whole signature in a code block below the heading. | `False` **`line_length`** | `int` | Maximum line length when formatting code. | `60` + **`merge_init_into_class`** | `bool` | Whether to merge the `__init__` method into the class' signature and docstring. | `False` **`show_source`** | `bool` | Show the source code of this object. | `True` **`show_bases`** | `bool` | Show the base classes of a class. | `True` **`show_submodules`** | `bool` | When rendering a module, show its submodules recursively. | `True` diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/children.html b/src/mkdocstrings_handlers/python/templates/material/_base/children.html index fe9a194d..6a5b40f5 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/children.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/children.html @@ -40,8 +40,10 @@ {% endif %} {% with heading_level = heading_level + extra_level %} {% for function in obj.functions.values()|order_members(config.members_order) %} - {% if not function.is_alias or function.is_explicitely_exported %} - {% include "function.html" with context %} + {% if not (obj.kind.value == "class" and function.name == "__init__" and config.merge_init_into_class) %} + {% if not function.is_alias or function.is_explicitely_exported %} + {% include "function.html" with context %} + {% endif %} {% endif %} {% endfor %} {% endwith %} @@ -65,25 +67,29 @@ {% for child in obj.members.values()|order_members(config.members_order) %} - {% if child.kind.value == "attribute" %} - {% with attribute = child %} - {% include "attribute.html" with context %} - {% endwith %} + {% if not (obj.kind.value == "class" and child.name == "__init__" and config.merge_init_into_class) %} - {% elif child.kind.value == "class" %} - {% with class = child %} - {% include "class.html" with context %} - {% endwith %} + {% if child.kind.value == "attribute" %} + {% with attribute = child %} + {% include "attribute.html" with context %} + {% endwith %} - {% elif child.kind.value == "function" %} - {% with function = child %} - {% include "function.html" with context %} - {% endwith %} + {% elif child.kind.value == "class" %} + {% with class = child %} + {% include "class.html" with context %} + {% endwith %} - {% elif child.kind.value == "module" and config.show_submodules %} - {% with module = child %} - {% include "module.html" with context %} - {% endwith %} + {% elif child.kind.value == "function" %} + {% with function = child %} + {% include "function.html" with context %} + {% endwith %} + + {% elif child.kind.value == "module" and config.show_submodules %} + {% with module = child %} + {% include "module.html" with context %} + {% endwith %} + + {% endif %} {% endif %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html b/src/mkdocstrings_handlers/python/templates/material/_base/class.html index 3b72f54a..97a5640b 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html @@ -22,14 +22,20 @@ class="doc doc-heading", toc_label=class.name) %} - - {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %} - {% if config.show_bases and class.bases %} - ({% for expression in class.bases -%} - {% include "expression.html" with context %}{% if not loop.last %}, {% endif %} - {% endfor %}) - {% endif %} - + {% if config.separate_signature %} + {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %} + {% elif config.merge_init_into_class and "__init__" in class.members -%} + {%- with function = class.members["__init__"] -%} + {%- filter highlight(language="python", inline=True) -%} + {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %} + {% with no_self = True %} + {%- include "signature.html" with context -%} + {% endwith %} + {%- endfilter -%} + {%- endwith -%} + {% else %} + {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %} + {% endif %} {% with labels = class.labels %} {% include "labels.html" with context %} @@ -37,6 +43,19 @@ {% endfilter %} + {% if config.separate_signature and config.merge_init_into_class %} + {% if "__init__" in class.members %} + {% with function = class.members["__init__"], no_self = True %} + {% filter highlight(language="python", inline=False) %} + {% filter format_signature(config.line_length) %} + {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %} + {% include "signature.html" with context %} + {% endfilter %} + {% endfilter %} + {% endwith %} + {% endif %} + {% endif %} + {% else %} {% if config.show_root_toc_entry %} {% filter heading(heading_level, @@ -50,15 +69,40 @@ {% endif %}
+ {% if config.show_bases and class.bases %} +

+ Bases: {% for expression in class.bases -%} + {% include "expression.html" with context %}{% if not loop.last %}, {% endif %} + {% endfor -%} +

+ {% endif %} + {% with docstring_sections = class.docstring.parsed %} {% include "docstring.html" with context %} {% endwith %} - {% if config.show_source and class.source %} -
- Source code in {{ class.relative_filepath }} - {{ class.source|highlight(language="python", linestart=class.lineno, linenums=True) }} -
+ {% if config.merge_init_into_class %} + {% if "__init__" in class.members and class.members["__init__"].has_docstring %} + {% with docstring_sections = class.members["__init__"].docstring.parsed %} + {% include "docstring.html" with context %} + {% endwith %} + {% endif %} + {% endif %} + + {% if config.show_source %} + {% if config.merge_init_into_class %} + {% if "__init__" in class.members %} +
+ Source code in {{ class.relative_filepath }} + {{ class.members["__init__"].source|highlight(language="python", linestart=class.lineno, linenums=True) }} +
+ {% endif %} + {% elif class.source %} +
+ Source code in {{ class.relative_filepath }} + {{ class.source|highlight(language="python", linestart=class.lineno, linenums=True) }} +
+ {% endif %} {% endif %} {% with obj = class %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html index d0a7fbe9..247aa081 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html @@ -10,30 +10,32 @@ ( {%- for parameter in function.parameters -%} + {%- if parameter.name != "self" or not no_self -%} - {%- if parameter.kind.value == "positional-only" -%} - {%- if ns.render_pos_only_separator -%} - {%- set ns.render_pos_only_separator = False %}/, {% endif -%} - {%- elif parameter.kind.value == "keyword-only" -%} - {%- if ns.render_kw_only_separator -%} - {%- set ns.render_kw_only_separator = False %}*, {% endif -%} - {%- endif -%} + {%- if parameter.kind.value == "positional-only" -%} + {%- if ns.render_pos_only_separator -%} + {%- set ns.render_pos_only_separator = False %}/, {% endif -%} + {%- elif parameter.kind.value == "keyword-only" -%} + {%- if ns.render_kw_only_separator -%} + {%- set ns.render_kw_only_separator = False %}*, {% endif -%} + {%- endif -%} - {%- if config.show_signature_annotations and parameter.annotation is not none -%} - {%- set annotation = ": " + parameter.annotation|safe -%} - {%- endif -%} + {%- if config.show_signature_annotations and parameter.annotation is not none -%} + {%- set annotation = ": " + parameter.annotation|safe -%} + {%- endif -%} - {%- 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 -%} + {%- 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 -%} - {%- if parameter.kind.value == "variadic positional" -%} - {%- set ns.render_kw_only_separator = False -%} - {%- endif -%} + {%- if parameter.kind.value == "variadic positional" -%} + {%- set ns.render_kw_only_separator = False -%} + {%- endif -%} - {{ parameter.name }}{{ annotation }}{{ default }} - {%- if not loop.last %}, {% endif -%} + {{ parameter.name }}{{ annotation }}{{ default }} + {%- if not loop.last %}, {% endif -%} + {%- endif -%} {%- endfor -%} ) {%- if config.show_signature_annotations and "return_annotation" in signature %} -> {{ signature.return_annotation }}{%- endif -%} From 7c49937a09581e1248d40f66bc2a3650ac98a25a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 13 Feb 2022 14:54:41 +0100 Subject: [PATCH 8/8] chore: Prepare release 0.6.0 --- CHANGELOG.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 745f8df6..9b51648e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,23 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). +## [0.6.0](https://github.com/mkdocstrings/python/releases/tag/0.6.0) - 2022-02-13 + +[Compare with 0.5.4](https://github.com/mkdocstrings/python/compare/0.5.4...0.6.0) + +### Features +- Add option to merge `__init__` methods' docstrings into their classes' docstrings ([1b4d1c0](https://github.com/mkdocstrings/python/commit/1b4d1c0e9254fc51756caed3875fbc8c1da079a6) by Timothée Mazzucotelli). +- Support separate attribute signature ([e962b88](https://github.com/mkdocstrings/python/commit/e962b885f48570762c5bfcefc9b61e5fc1df1c70) by Timothée Mazzucotelli). + +### Bug Fixes +- Restore full cross-refs paths on hover ([ac11970](https://github.com/mkdocstrings/python/commit/ac1197062f2e23e819f144fe74a774d504d0ac49) by Timothée Mazzucotelli). +- Fix rendering of labels ([52919c5](https://github.com/mkdocstrings/python/commit/52919c559378a6006bbe931423c5f03eb5883eaf) by Timothée Mazzucotelli). + +### Code Refactoring +- Don't add trailing parentheses in functions heading when separate signature ([885696e](https://github.com/mkdocstrings/python/commit/885696e05606d07334e0428128ed688d54098da1) by Timothée Mazzucotelli). +- Use more explicit template debug messages ([f2122d7](https://github.com/mkdocstrings/python/commit/f2122d7fa119ed055ffe2b2bac72d2c643daca1c) by Timothée Mazzucotelli). + + ## [0.5.4](https://github.com/mkdocstrings/python/releases/tag/0.5.4) - 2022-02-13 [Compare with 0.5.3](https://github.com/mkdocstrings/python/compare/0.5.3...0.5.4)