diff --git a/CHANGELOG.md b/CHANGELOG.md index 207a8803..619b7ee7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,18 @@ 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). +## [1.6.0](https://github.com/mkdocstrings/python/releases/tag/1.6.0) - 2023-08-27 + +[Compare with 1.5.2](https://github.com/mkdocstrings/python/compare/1.5.2...1.6.0) + +### Features + +- Add `doc-signature` CSS class to separate signature code blocks ([b6c648f](https://github.com/mkdocstrings/python/commit/b6c648f554f2e0dce609afc2a2c1a3b27a4fbeba) by Timothée Mazzucotelli). + +### Code Refactoring + +- Add a `format_attribute` filter, preparing for cross-refs in attribute signatures ([8f0ade2](https://github.com/mkdocstrings/python/commit/8f0ade249638ee2f2d446f083c70b6c30799875a) by Timothée Mazzucotelli). + ## [1.5.2](https://github.com/mkdocstrings/python/releases/tag/1.5.2) - 2023-08-25 [Compare with 1.5.1](https://github.com/mkdocstrings/python/compare/1.5.1...1.5.2) diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index 7b3a8a50..14d31f88 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -352,6 +352,7 @@ def update_env(self, md: Markdown, config: dict) -> None: # noqa: D102 (ignore self.env.filters["order_members"] = rendering.do_order_members self.env.filters["format_code"] = rendering.do_format_code self.env.filters["format_signature"] = rendering.do_format_signature + self.env.filters["format_attribute"] = rendering.do_format_attribute self.env.filters["filter_objects"] = rendering.do_filter_objects self.env.filters["stash_crossref"] = lambda ref, length: ref self.env.filters["get_template"] = rendering.do_get_template diff --git a/src/mkdocstrings_handlers/python/rendering.py b/src/mkdocstrings_handlers/python/rendering.py index de20f799..b2869bf9 100644 --- a/src/mkdocstrings_handlers/python/rendering.py +++ b/src/mkdocstrings_handlers/python/rendering.py @@ -14,7 +14,7 @@ from mkdocstrings.loggers import get_logger if TYPE_CHECKING: - from griffe.dataclasses import Alias, Function, Object + from griffe.dataclasses import Alias, Attribute, Function, Object from jinja2.runtime import Context from mkdocstrings.handlers.base import CollectorItem @@ -104,7 +104,54 @@ def do_format_signature( template = env.get_template("signature.html") signature = template.render(context.parent, function=function) signature = _format_signature(callable_path, signature, line_length) - return str(env.filters["highlight"](signature, language="python", inline=False)) + return str( + env.filters["highlight"]( + signature, + language="python", + inline=False, + classes=["doc-signature"], + ), + ) + + +@pass_context +def do_format_attribute( + context: Context, + attribute_path: Markup, + attribute: Attribute, + line_length: int, + *, + crossrefs: bool = False, # noqa: ARG001 +) -> str: + """Format an attribute using Black. + + Parameters: + attribute_path: The path of the callable we render the signature of. + attribute: The attribute we render the signature of. + line_length: The line length to give to Black. + crossrefs: Whether to cross-reference types in the signature. + + Returns: + The same code, formatted. + """ + env = context.environment + annotations = context.parent["config"]["show_signature_annotations"] + + signature = str(attribute_path).strip() + if annotations and attribute.annotation: + signature += f": {attribute.annotation}" + if attribute.value: + signature += f" = {attribute.value}" + + signature = do_format_code(signature, line_length) + return str( + env.filters["highlight"]( + Markup.escape(signature), + language="python", + inline=False, + classes=["doc-signature"], + ), + ) def do_order_members( diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html index c9fa126f..764e9a7d 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html @@ -44,11 +44,8 @@ {% block signature scoped %} {% if config.separate_signature %} - {% filter highlight(language="python", inline=False) %} - {% filter format_code(config.line_length) %} - {{ attribute.name }}{% if attribute.annotation %}: {{ attribute.annotation|safe }}{% endif %} - {% if attribute.value %} = {{ attribute.value|safe }}{% endif %} - {% endfilter %} + {% filter format_attribute(attribute, config.line_length, crossrefs=config.signature_crossrefs) %} + {{ attribute.name }} {% endfilter %} {% endif %} {% endblock signature %}