preserve preformatted help text

The config options are an interface to a subset of users. These users
need to read and understand the help text of the options. To make it
easier to read, it should be possible to preformat the text. This
patch set keeps the preformat with line breaks.

Change-Id: I8aa871001f7da3cefcd9aa93992d50d0d9140157

doc/source/styleguide.rst

@@ -69,3 +69,16 @@ Format
                       'can improve data throughput, such as when high '
                       'network bandwidth is available and you use '
                       'compressed image formats like qcow2.')
+
+2. It is possible to preformat the multi-line strings to increase readability.
+   Line break characters ``\n`` will be kept as they are used in the help text.
+   Example::
+
+     cfg.IntOpt('sync_power_state_interval',
+                default=600,
+                help='Interval to sync power states between the database and '
+                     'the hypervisor.\n'
+                     '\n'
+                     '-1: disables the sync \n'
+                     ' 0: run at the default rate.\n'
+                     '>0: the interval in seconds')

oslo_config/generator.py

@@ -88,10 +88,16 @@ class _OptFormatter(object):
         :param help_text: The text of the help string
         """
         if self.wrap_width is not None and self.wrap_width > 0:
-            lines = [textwrap.fill(help_text,
-                                   self.wrap_width,
-                                   initial_indent='# ',
-                                   subsequent_indent='# ') + '\n']
+            wrapped = ""
+            for line in help_text.splitlines():
+                text = "\n".join(textwrap.wrap(line, self.wrap_width,
+                                               initial_indent='# ',
+                                               subsequent_indent='# ',
+                                               break_long_words=False,
+                                               replace_whitespace=False))
+                wrapped += "#" if text == "" else text
+                wrapped += "\n"
+            lines = [wrapped]
         else:
             lines = ['# ' + help_text + '\n']
         return lines

oslo_config/tests/test_generator.py

@@ -48,6 +48,19 @@ class GeneratorTestCase(base.BaseTestCase):
                                      'cupidatat non proident, sunt in culpa '
                                      'qui officia deserunt mollit anim id est '
                                      'laborum.'),
+        'long_help_pre': cfg.StrOpt('long_help_pre',
+                                    help='This is a very long help text which '
+                                         'is preformatted with line breaks. '
+                                         'It should break when it is too long '
+                                         'but also keep the specified line '
+                                         'breaks. This makes it possible to '
+                                         'create lists with items:\n'
+                                         '\n'
+                                         '* item 1\n'
+                                         '* item 2\n'
+                                         '\n'
+                                         'and should increase the '
+                                         'readability.'),
         'choices_opt': cfg.StrOpt('choices_opt',
                                   default='a',
                                   choices=(None, '', 'a', 'b', 'c'),
@@ -288,6 +301,26 @@ class GeneratorTestCase(base.BaseTestCase):
 '(string value)'
 '''
 #long_help = <None>
+''')),
+        ('long_help_with_preformatting',
+         dict(opts=[('test', [(None, [opts['long_help_pre']])])],
+              wrap_width=70,
+              expected='''[DEFAULT]
+
+#
+# From test
+#
+
+# This is a very long help text which is preformatted with line
+# breaks. It should break when it is too long but also keep the
+# specified line breaks. This makes it possible to create lists with
+# items:
+#
+# * item 1
+# * item 2
+#
+# and should increase the readability. (string value)
+#long_help_pre = <None>
 ''')),
         ('choices_opt',
          dict(opts=[('test', [(None, [opts['choices_opt']])])],