[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 9e5e702797b62388de819624823f96c5400c2668..2cb562d5233ed35fd34cb5d9d5a7538e6285475d 100644 (file)
--- 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()