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