render_description() and layout exploration

httpie/cli/definition.py

@@ -112,8 +112,7 @@ positional_arguments.add_argument(
 
         search==httpie
 
-    '=' Data fields to be serialized into a JSON object (with --json, -j)
-        or form data (with --form, -f):
+    '=' Data fields to be serialized into a JSON object (with --json, -j) or form data (with --form, -f):
 
         name=HTTPie  language=Python  description='CLI HTTP client'
 
@@ -246,7 +245,7 @@ def format_style_help(available_styles, *, isolation_mode: bool = False):
     text = """
     Output coloring style (default is "{default}"). It can be one of:
 
-        {available_styles}
+    {available_styles}
     """
     if isolation_mode:
         text += '\n\n'
@@ -472,8 +471,8 @@ output_options.add_argument(
     requests/responses (such as redirects). For the second level and higher,
     print these as well as the response metadata.
 
-    Level one is a shortcut for: --all --print={''.join(sorted(BASE_OUTPUT_OPTIONS))}
-    Level two is a shortcut for: --all --print={''.join(sorted(OUTPUT_OPTIONS))}
+        -v (level one) is a shortcut for:  --all --print={''.join(sorted(BASE_OUTPUT_OPTIONS))}
+        -vv (level two) is a shortcut for: --all --print={''.join(sorted(OUTPUT_OPTIONS))}
     """,
 )
 output_options.add_argument(
@@ -629,7 +628,7 @@ def format_auth_help(auth_plugins_mapping, *, isolation_mode: bool = False):
     text = """
     The authentication mechanism to be used. Defaults to "{default}".
 
-    {auth_types}
+{auth_types}
     """
 
     auth_plugins = list(auth_plugins_mapping.values())
@@ -643,8 +642,8 @@ def format_auth_help(auth_plugins_mapping, *, isolation_mode: bool = False):
         text += 'For finding out all available authentication types in your system, try:\n\n'
         text += '    $ http --auth-type'
 
-    auth_types = '\n\n    '.join(
-        '"{type}": {name}{package}{description}'.format(
+    auth_types = '\n'.join(
+        '        "{type}": {name}{package}{description}'.format(
             type=plugin.auth_type,
             name=plugin.name,
             package=(

httpie/output/ui/rich_help.py

@@ -42,6 +42,32 @@ class OptionsHighlighter(RegexHighlighter):
 options_highlighter = OptionsHighlighter()
 
 
+def render_description(raw: str) -> str:
+    final = []
+    line_break = '\n'
+    space = ' '
+    para = line_break + line_break
+    empty_line = False
+    for line in raw.splitlines():
+        if not line:
+            empty_line = True
+            continue
+
+        is_indented = line.startswith(space)
+        is_prev_indented = final and final[-1].startswith(space)
+
+        if not empty_line and not is_indented and final:
+            final.append(space)
+        elif empty_line:
+            final.append(para)
+        if is_prev_indented and is_indented:
+            final.append(line_break)
+        final.append(line)
+        empty_line = False
+
+    return ''.join(final)
+
+
 def unpack_argument(
     argument: Argument,
 ) -> Tuple[Text, Text]:
@@ -153,10 +179,11 @@ def to_help_message(
                 )
                 description.append('\n')
             elif raw_form.get('choices'):
-                description.append(f'{{{", ".join(raw_form["choices"])}}}')
+                description.append(Text(f'{{{", ".join(raw_form["choices"])}}}', style=STYLE_METAVAR))
                 description.append('\n')
 
             description_text = raw_form.get('description', '').strip()
+            description_text = render_description(description_text)
             # description_text = SINGLE_NEWLINE_RE.sub(' ', description_text)
             description.append(description_text)
             description.append('\n')