From: Travis Rhoden <trhoden@redhat.com>
Date: Wed, 1 Jul 2015 20:45:44 +0000 (-0700)
Subject: [RM-12151] Add description to ToggleRawTextHelpFormatter
X-Git-Tag: v1.5.26~13^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F313%2Fhead;p=ceph-deploy.git

[RM-12151] Add description to ToggleRawTextHelpFormatter

Signed-off-by: Travis Rhoden <trhoden@redhat.com>
---

diff --git a/ceph_deploy/util/help_formatters.py b/ceph_deploy/util/help_formatters.py
index 9e5e702..2cb562d 100644
--- a/ceph_deploy/util/help_formatters.py
+++ b/ceph_deploy/util/help_formatters.py
@@ -2,9 +2,31 @@ import argparse
 
 
 class ToggleRawTextHelpFormatter(argparse.HelpFormatter):
-    """Inspired by the SmartFormatter at
-       https://bitbucket.org/ruamel/std.argparse
-   """
+    """ArgParse help formatter that allows raw text in individual help strings
+
+        Inspired by the SmartFormatter at
+           https://bitbucket.org/ruamel/std.argparse
+
+       Normally to include newlines in the help output of argparse, you have
+       use argparse.RawDescriptionHelpFormatter. But this means raw text is enabled
+       everywhere, and not just for specific help entries where you might need it.
+
+       This help formatter allows for you to optional enable/toggle raw text on
+       individual menu items by prefixing the help string with 'R|'.
+
+       Example:
+
+       parser.formatter_class = ToggleRawTextHelpFormatter
+       parser.add_argument('--verbose', action=store_true,
+                           help='Enable verbose mode')
+       #Above help is formatted just as default argparse.HelpFormatter
+
+       parser.add_argument('--complex-arg', action=store_true,
+                           help=('R|This help description use '
+                                 'newlines and tabs and they will be preserved in'
+                                 'the help output.\n\n'
+                                 '\tHow cool is that?'))
+    """
     def _split_lines(self, text, width):
         if text.startswith('R|'):
             return text[2:].splitlines()