diff --git a/changelogs/fragments/83155-ansible-doc-paragraphs.yml b/changelogs/fragments/83155-ansible-doc-paragraphs.yml
new file mode 100644
index 00000000000..b92bd526b77
--- /dev/null
+++ b/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)."
diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py
index 16033f8e112..0e0b7631f14 100755
--- a/lib/ansible/cli/doc.py
+++ b/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'))
diff --git a/test/integration/targets/ansible-doc/randommodule-text.output b/test/integration/targets/ansible-doc/randommodule-text.output
index e647576fa71..ac90e38f0cb 100644
--- a/test/integration/targets/ansible-doc/randommodule-text.output
+++ b/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
- 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 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