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,9 +1296,10 @@ class DocCLI(CLI, RoleMixin):
 
             if doc.get('description'):
                 if isinstance(doc['description'], list):
-                    desc = " ".join(doc['description'])
+                    descs = doc['description']
                 else:
-                    desc = doc['description']
+                    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('')
 
@@ -1355,11 +1356,12 @@ 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('')
+        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:

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
+  A random module.
-  entrypoint) for how this is used in the [[foo.bar.baz]]'s `main'
+  See `foo=bar' (of role foo.bar.baz, main entrypoint) for how this is
-  entrypoint. See the docsite
+  used in the [[foo.bar.baz]]'s `main' entrypoint.
-  <https://docs.ansible.com/ansible-core/devel/> for more information
+  See the docsite <https://docs.ansible.com/ansible-core/devel/> for
-  on ansible-core. This module is not related to the
+  more information on ansible-core.
-  [ansible.builtin.copy] module.  -------------  You might also be
+  This module is not related to the [ansible.builtin.copy] module.
-  interested in ansible_python_interpreter. Sometimes you have [broken
+  -------------  You might also be interested in
-  markup] that will result in error messages.
+  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