fix: Preserve multiline help text formatting.

Author: DanCardin

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 0.32
 
 ### 0.32.2
+- fix: Preserve multiline help text formatting.
 - fix: Dedent attribute docstrings' content.
 
 ### 0.32.1

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cappa"
-version = "0.32.1"
+version = "0.32.2"
 description = "Declarative CLI argument parser."
 
 urls = { repository = "https://github.com/dancardin/cappa" }

src/cappa/help.py

@@ -271,29 +271,45 @@ def format_args(
 
 
 def _markdown_to_text(console: Console, renderables: Sequence[TextComponent]) -> Text:
+    # Render the text without line-wrapping because we're not yet printing it and it should reflow
+    # until the point at which it's being printed to the user.
+    render_console = Console(soft_wrap=True)
+    render_options = render_console.options.update(no_wrap=True, overflow="ignore")
+
     result = Text()
     for renderable in renderables:
         if isinstance(renderable, Markdown):
-            for segment in console.render(renderable):
-                text = segment.text.strip("\n")
+            renderable_result = Text()
+            for segment in render_console.render(renderable, render_options):
+                text = segment.text
+                if not text:
+                    continue
                 if text.startswith(" "):  # dedup leading spaces
                     text = " " + text.lstrip()
                 if text.endswith(" "):  # dedup trailing spaces
                     text = text.rstrip() + " "
-                if text:
-                    result.append(Text(text, style=segment.style or "", end=""))
+                renderable_result.append(Text(text, style=segment.style or "", end=""))
+            renderable_result.rstrip()
+            if renderable_result:
+                _append_to_text(result, renderable_result)
         else:
-            if result:
-                result.append(" ")
-
             if isinstance(renderable, str):
                 renderable = Text.from_markup(renderable)
 
-            result.append(renderable)
+            _append_to_text(result, renderable)
 
     return result
 
 
+def _append_to_text(text: Text, component: Text) -> None:
+    # When a component is multiline (like long, structured {help}), it looks weird when components
+    # like {choices} or {default} are appended to the end of the last line. In such cases, add a newline.
+    # Sort of a weird heuristic, we'll see if this holds well in practice.
+    if text:
+        text.append("\n" if "\n" in text.plain else " ")
+    text.append(component)
+
+
 def _get_text_component_text(c: TextComponent) -> str:
     if isinstance(c, Text):
         return c.plain

tests/help/test_markdown.py

@@ -4,9 +4,16 @@
 
 import pytest
 from rich.console import Console
+from typing_extensions import Annotated
 
 import cappa
-from tests.utils import Backend, backends, parse
+from tests.utils import (
+    Backend,
+    backends,
+    parse,
+    strip_trailing_whitespace,
+    terminal_width,
+)
 
 
 @pytest.mark.help
@@ -38,3 +45,57 @@ class Args:
     assert "This\x1b[0m" in result.out
     assert " \x1b[1mis\x1b[0m" in result.out  # typos: ignore
     assert " \x1b[3mneat\x1b[0m" in result.out
+
+
+@pytest.mark.help
+@backends
+def test_multi_paragraph_arg_help_preserves_paragraph_breaks(
+    backend: Backend, capsys: Any
+):
+    @dataclass
+    class Args:
+        foo: Annotated[
+            str,
+            cappa.Arg(
+                help="First paragraph summary.\n\nSecond paragraph body.",
+            ),
+        ]
+
+    with terminal_width(80), pytest.raises(cappa.Exit):
+        parse(Args, "--help", backend=backend)
+
+    out = strip_trailing_whitespace(capsys.readouterr().out)
+
+    assert "First paragraph summary." in out
+    assert "Second paragraph body." in out
+
+    summary_pos = out.index("First paragraph summary.")
+    body_pos = out.index("Second paragraph body.")
+    between = out[summary_pos + len("First paragraph summary.") : body_pos]
+    assert "\n\n" in between
+
+
+@pytest.mark.help
+@backends
+def test_soft_line_breaks_fold_into_spaces(backend: Backend, capsys: Any):
+    @dataclass
+    class SoftBreakArgs:
+        foo: str
+        """
+        This is a long sentence that goes on and on.
+        This second soft-break line continues the same paragraph.
+        """
+
+    with terminal_width(80), pytest.raises(cappa.Exit):
+        parse(SoftBreakArgs, "--help", backend=backend, completion=False)
+
+    out = strip_trailing_whitespace(capsys.readouterr().out)
+
+    # Words from adjacent soft-break lines must be separated by a space
+    assert "on.This" not in out
+    assert "on. This" in out
+
+    # And must not have a blank line between them (same paragraph)
+    first = out.index("goes on and on.")
+    second = out.index("same paragraph.")
+    assert "\n\n" not in out[first:second]

tests/test_docstring.py

@@ -7,40 +7,57 @@
 
 def test_attribute_docstring_single_line():
     @dataclass
-    class Args:
+    class SingleLineArgs:
         foo: int
         """A simple description."""
 
-    result = get_attribute_docstrings(Args)
+    result = get_attribute_docstrings(SingleLineArgs)
     assert result == {"foo": "A simple description."}
 
 
 def test_attribute_docstring_indented_multiline():
     @dataclass
-    class Args:
+    class IndentedMultilineArgs:
         foo: int
         """First paragraph.
 
         Second paragraph.
         """
 
-    result = get_attribute_docstrings(Args)
+    result = get_attribute_docstrings(IndentedMultilineArgs)
     assert result == {"foo": "First paragraph.\n\nSecond paragraph."}
 
 
 def test_attribute_docstring_indented_multiline_dedented():
     """Indented attribute docstrings must not be treated as Markdown code blocks."""
 
     @dataclass
-    class Args:
+    class IndentedDedentedArgs:
         foo: int
         """Summary line.
 
         Body paragraph that would have 8 spaces of indent before cleandoc,
         with a long enough body to wrap.
         """
 
-    result = get_attribute_docstrings(Args)
+    result = get_attribute_docstrings(IndentedDedentedArgs)
 
     # No leading spaces on continuation lines
     assert not any(line.startswith("    ") for line in result["foo"].splitlines())
+
+
+def test_attribute_docstring_multiple_fields():
+    @dataclass
+    class MultipleFieldArgs:
+        foo: int
+        """Foo help.
+
+        Foo body.
+        """
+
+        bar: str
+        """Bar help."""
+
+    result = get_attribute_docstrings(MultipleFieldArgs)
+    assert result["foo"] == "Foo help.\n\nFoo body."
+    assert result["bar"] == "Bar help."