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,46 @@ 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']
+
+    >>> _get_paragraphs('''
+    * Acme bullet
+    - Another bullet
+    Continuing...
+
+    Finished''')
+    ['* Acme bullet', '- Another bullet. Continuing', 'Finished']
+    """
+    output = []
+    paragraph = []
+    for line in text.split('\n'):
+        line = line.strip()
+        if not line:  # blank lines
+            if paragraph:
+                output.append(' '.join(paragraph))
+                paragraph = []
+        elif line.startswith(('- ', '* ')):  # bullet points
+            if paragraph:
+                output.append(' '.join(paragraph))
+                paragraph = []
+            paragraph.append(line.strip())
+        else:  # ...and everything 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):]
@@ -480,14 +520,8 @@ def write_files(package_name, options, target, output_format):
             if not option.help:
                 option.help = "No help text available for this option."
 
-            helptext = _remove_prefix(
-                option.help.strip(), 'DEPRECATED').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(':'))
 
             if not option.deprecated_reason:
                 option.deprecated_reason = (
@@ -507,8 +541,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

@@ -20,13 +20,20 @@
    * - **[{{ group }}]**
      -
 {% for item in items[loop.index0] %}
-{% if item[1] is equalto '' %}
+{% if item[2] 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 %}