Simplify the format of paragraphs

There's a rather complicated bit of code used to split blocks of text
into paragraphs. Replace this with something a little simpler that makes
use of our paragraph-ization rather than trying to rebuild blocks of
text.

This also fixes an issue with some options that are incorrectly
formatted with random block indents.

Change-Id: I321ba57d0f7090afec34c6207f9a42493b8a3249

autogenerate_config_docs/autohelp.py

@@ -423,6 +423,38 @@ def _get_category_names(package_name):
     return category_names
 
 
+def _get_paragraphs(text):
+    """Breaks a string into paragraphs.
+
+    >>> _get_paragraphs('''
+    Hello, world.
+    This is a run on line.
+
+    But this is a paragraph''')
+    ['Hello, world. This is a run on line', 'But this is a paragraph']
+    """
+    output = []
+    paragraph = []
+    for line in text.split('\n'):
+        if not line.strip():
+            if paragraph:
+                output.append(' '.join(paragraph))
+                paragraph = []
+        else:
+            paragraph.append(line.strip())
+
+    if paragraph:
+        output.append(' '.join(paragraph))
+
+    return output
+
+
+def _remove_prefix(text, prefix):
+    if text.startswith(prefix):
+        return text[len(prefix):]
+    return text
+
+
 def write_files(package_name, options, target, output_format):
     """Write tables.
 
@@ -474,17 +506,8 @@ def write_files(package_name, options, target, output_format):
             if not option.help:
                 option.help = "No help text available for this option."
 
-
-            _prefix = 'DEPRECATED'
-            helptext = option.help.strip()
-            helptext = helptext[
-                helptext.startswith(_prefix) and len(_prefix):].lstrip(': ')
-            helptext = re.sub(r'\n+\s*\* ', '$sentinal$* ', helptext)
-            helptext = helptext.replace('\n\n', '$sentinal$')
-            helptext = helptext.replace('\n', ' ')
-            helptext = ' '.join(helptext.split())
-            # TODO(johngarbutt) space matches only the current template :(
-            helptext = helptext.replace('$sentinal$', '\n\n       ')
+            help_text = _get_paragraphs(_remove_prefix(
+                option.help, 'DEPRECATED').lstrip(':'))
 
             deprecated_reason = ' '.join([x.strip() for x in (
                 option.deprecated_reason or '').split('\n')])
@@ -500,8 +523,9 @@ def write_files(package_name, options, target, output_format):
                               ' restarting.'))
 
             item = (option.dest,
+                    opt_type,
                     _sanitize_default(option),
-                    "(%s) %s" % (opt_type, helptext),
+                    help_text,
                     flags)
             items.append(item)
 

autogenerate_config_docs/templates/autohelp.rst.j2

@@ -23,10 +23,17 @@
 {% if item[1] is equalto '' %}
    * - ``{{ item[0] }}`` =
 {% else %}
-   * - ``{{ item[0] }}`` = ``{{ item[1] }}``
+   * - ``{{ item[0] }}`` = ``{{ item[2] }}``
 {% endif %}
-     - {{ item[2] }}
-{% for flagname, flagdesc in item[3] %}
+{% for paragraph in item[3] %}
+{% if loop.first %}
+     - ({{ item [1] }}) {{ paragraph }}
+{% else %}
+       {{ paragraph }}
+{% endif %}
+
+{% endfor %}
+{% for flagname, flagdesc in item[4] %}
      - **{{ flagname }}**
          {{ flagdesc }}
 {% endfor %}