refactor: Add a format_attribute filter, preparing for cross-refs in attribute signatures

Author: pawamoy

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

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
 
@@ -107,6 +107,45 @@ def do_format_signature(
     return str(env.filters["highlight"](signature, language="python", inline=False))
 
 
+@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,
+        ),
+    )
+
+
 def do_order_members(
     members: Sequence[Object | Alias],
     order: Order,

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 %}