Correctly treat separate paragraphs in top-level descriptions as separate paragraphs. (#83155)

changelogs/fragments/83155-ansible-doc-paragraphs.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - "ansible-doc - format top-level descriptions with multiple paragraphs as multiple paragraphs, instead of concatenating them (https://github.com/ansible/ansible/pull/83155)."

lib/ansible/cli/doc.py

@@ -1296,10 +1296,11 @@ class DocCLI(CLI, RoleMixin):
 
             if doc.get('description'):
                 if isinstance(doc['description'], list):
-                    desc = " ".join(doc['description'])
+                    descs = doc['description']
                 else:
-                    desc = doc['description']
-                text.append("%s" % DocCLI.warp_fill(DocCLI.tty_ify(desc), limit, initial_indent=opt_indent, subsequent_indent=opt_indent))
+                    descs = [doc['description']]
+                for desc in descs:
+                    text.append("%s" % DocCLI.warp_fill(DocCLI.tty_ify(desc), limit, initial_indent=opt_indent, subsequent_indent=opt_indent))
                 text.append('')
 
             if doc.get('options'):
@@ -1355,12 +1356,13 @@ class DocCLI(CLI, RoleMixin):
         text.append("> %s %s (%s)" % (plugin_type.upper(), _format(doc.pop('plugin_name'), 'bold'), doc.pop('filename')))
 
         if isinstance(doc['description'], list):
-            desc = " ".join(doc.pop('description'))
+            descs = doc.pop('description')
         else:
-            desc = doc.pop('description')
+            descs = [doc.pop('description')]
 
         text.append('')
-        text.append(DocCLI.warp_fill(DocCLI.tty_ify(desc), limit, initial_indent=base_indent, subsequent_indent=base_indent))
+        for desc in descs:
+            text.append(DocCLI.warp_fill(DocCLI.tty_ify(desc), limit, initial_indent=base_indent, subsequent_indent=base_indent))
 
         if display.verbosity > 0:
             doc['added_in'] = DocCLI._format_version_added(doc.pop('version_added', 'historical'), doc.pop('version_added_collection', 'ansible-core'))

test/integration/targets/ansible-doc/randommodule-text.output

@@ -1,13 +1,15 @@
 > MODULE testns.testcol.randommodule (./collections/ansible_collections/testns/testcol/plugins/modules/randommodule.py)
 
-  A random module. See `foo=bar' (of role foo.bar.baz, main
-  entrypoint) for how this is used in the [[foo.bar.baz]]'s `main'
-  entrypoint. See the docsite
-  <https://docs.ansible.com/ansible-core/devel/> for more information
-  on ansible-core. This module is not related to the
-  [ansible.builtin.copy] module.  -------------  You might also be
-  interested in ansible_python_interpreter. Sometimes you have [broken
-  markup] that will result in error messages.
+  A random module.
+  See `foo=bar' (of role foo.bar.baz, main entrypoint) for how this is
+  used in the [[foo.bar.baz]]'s `main' entrypoint.
+  See the docsite <https://docs.ansible.com/ansible-core/devel/> for
+  more information on ansible-core.
+  This module is not related to the [ansible.builtin.copy] module.
+  -------------  You might also be interested in
+  ansible_python_interpreter.
+  Sometimes you have [broken markup] that will result in error
+  messages.
 DEPRECATED: 
 	Reason: Test deprecation
 	Will be removed in: Ansible 3.0.0