api-style(feat[transforms]): prune empty desc_content after badge injection

why: Undocumented autodoc objects left empty desc_content, producing blank
<dd> rows and extra vertical space in API cards.
what:
- Add _prune_empty_desc_content with doctest
- Invoke it from on_doctree_resolved for handled py desc nodes
- Add unit tests for direct prune, nonempty preserve, and pipeline

Author: tony

packages/sphinx-autodoc-api-style/src/sphinx_autodoc_api_style/_transforms.py

@@ -188,6 +188,32 @@ def _inject_badges(sig_node: addnodes.desc_signature, objtype: str) -> None:
     sig_node += toolbar
 
 
+def _prune_empty_desc_content(desc_node: addnodes.desc) -> None:
+    """Remove empty desc_content nodes from a desc tree.
+
+    Sphinx always appends a desc_content child even when the object has
+    no docstring. An empty <dd></dd> wastes vertical space and creates
+    layout noise. Remove it so the CSS card only shows the signature row.
+
+    Parameters
+    ----------
+    desc_node : addnodes.desc
+        The description node to inspect.
+
+    Examples
+    --------
+    >>> from sphinx import addnodes
+    >>> desc = addnodes.desc()
+    >>> desc += addnodes.desc_content()          # empty
+    >>> _prune_empty_desc_content(desc)
+    >>> any(isinstance(c, addnodes.desc_content) for c in desc.children)
+    False
+    """
+    for child in list(desc_node.children):
+        if isinstance(child, addnodes.desc_content) and not child.children:
+            desc_node.remove(child)
+
+
 def on_doctree_resolved(
     app: Sphinx,
     doctree: nodes.document,
@@ -230,3 +256,4 @@ def on_doctree_resolved(
         for child in desc_node.children:
             if isinstance(child, addnodes.desc_signature):
                 _inject_badges(child, objtype)
+        _prune_empty_desc_content(desc_node)

tests/ext/api_style/test_api_style.py

@@ -23,6 +23,7 @@
     _detect_deprecated,
     _detect_modifiers,
     _inject_badges,
+    _prune_empty_desc_content,
     on_doctree_resolved,
 )
 
@@ -413,6 +414,55 @@ def test_inject_badges_headerlink_not_in_toolbar() -> None:
     assert len(sig_direct_refs) == 1, "headerlink should remain a direct child of sig"
 
 
+# ---------------------------------------------------------------------------
+# _prune_empty_desc_content
+# ---------------------------------------------------------------------------
+
+
+def test_prune_empty_desc_content_removes_empty() -> None:
+    """Empty desc_content is removed from the desc node."""
+    desc = addnodes.desc()
+    desc += addnodes.desc_signature()
+    desc += addnodes.desc_content()  # empty — no children
+
+    _prune_empty_desc_content(desc)
+
+    assert not any(isinstance(c, addnodes.desc_content) for c in desc.children)
+
+
+def test_prune_empty_desc_content_keeps_nonempty() -> None:
+    """desc_content with children is not removed."""
+    desc = addnodes.desc()
+    content = addnodes.desc_content()
+    content += nodes.paragraph("", "Has content.")
+    desc += addnodes.desc_signature()
+    desc += content
+
+    _prune_empty_desc_content(desc)
+
+    assert any(isinstance(c, addnodes.desc_content) for c in desc.children)
+
+
+def test_on_doctree_resolved_prunes_empty_desc_content() -> None:
+    """on_doctree_resolved removes empty desc_content via full pipeline."""
+    from unittest.mock import MagicMock
+
+    app = MagicMock()
+    doc = nodes.document(None, None)  # type: ignore[arg-type]
+    desc = addnodes.desc()
+    desc["domain"] = "py"
+    desc["objtype"] = "attribute"
+    sig = addnodes.desc_signature()
+    sig += addnodes.desc_name("", "session_id")
+    desc += sig
+    desc += addnodes.desc_content()  # empty — simulates undocumented attribute
+
+    doc += desc
+    on_doctree_resolved(app, doc, "index")
+
+    assert not any(isinstance(c, addnodes.desc_content) for c in desc.children)
+
+
 # ---------------------------------------------------------------------------
 # on_doctree_resolved
 # ---------------------------------------------------------------------------