Display full command documentation in online help

ipa <command> -h only showed the summary string, not the full help.
Use the full docstring. Add a custom help formatter that disables
optparse's reformatting.

Test included

https://fedorahosted.org/freeipa/ticket/3543

ipalib/cli.py

@@ -1098,7 +1098,8 @@ class cli(backend.Executioner):
     def build_parser(self, cmd):
         parser = CLIOptionParser(
             usage=' '.join(self.usage_iter(cmd)),
-            description=cmd.summary,
+            description=unicode(cmd.doc),
+            formatter=IPAHelpFormatter(),
         )
         option_groups = {}
         for option in cmd.options():
@@ -1257,6 +1258,21 @@ class cli(backend.Executioner):
                 kw[p.name] = self.Backend.textui.decode(raw)
 
 
+class IPAHelpFormatter(optparse.IndentedHelpFormatter):
+    """Formatter suitable for printing IPA command help
+
+    The default help formatter reflows text to fit the terminal, but it
+    ignores line/paragraph breaks.
+    IPA's descriptions already have correct line breaks. This formatter
+    doesn't touch them (save for removing initial/trailing whitespace).
+    """
+    def format_description(self, description):
+        if description:
+            return description.strip()
+        else:
+            return ""
+
+
 cli_plugins = (
     cli,
     textui,

tests/test_cmdline/test_help.py

@@ -128,3 +128,14 @@ def test_ambiguous_command_or_topic():
     assert h_ctx.stderr == ''
 
     assert h_ctx.stdout != help_ctx.stdout
+
+def test_multiline_description():
+    """Test that all of a multi-line command description appears in output
+    """
+    # This assumes trust_add has multiline doc. Ensure it is so.
+    assert '\n\n' in unicode(api.Command.trust_add.doc).strip()
+
+    with CLITestContext(exception=SystemExit) as help_ctx:
+        return_value = api.Backend.cli.run(['trust-add', '-h'])
+
+    assert unicode(api.Command.trust_add.doc).strip() in help_ctx.stdout