From 585ef6c55e87c10c1ce7d59ebe9c33dd6dbe5afb Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Wed, 1 May 2024 17:27:50 +0200
Subject: [PATCH] Show examples in role entrypoint argument specs. (#82671)

---
 .../fragments/82671-ansible-doc-role-examples.yml     |  2 ++
 lib/ansible/cli/doc.py                                | 11 +++++++++++
 .../testns/testcol/roles/testrole/meta/main.yml       |  3 +++
 .../targets/ansible-doc/fakecollrole.output           |  4 ++++
 4 files changed, 20 insertions(+)
 create mode 100644 changelogs/fragments/82671-ansible-doc-role-examples.yml

diff --git a/changelogs/fragments/82671-ansible-doc-role-examples.yml b/changelogs/fragments/82671-ansible-doc-role-examples.yml
new file mode 100644
index 00000000000..7f041babc5b
--- /dev/null
+++ b/changelogs/fragments/82671-ansible-doc-role-examples.yml
@@ -0,0 +1,2 @@
+minor_changes:
+  - "ansible-doc - show examples in role entrypoint argument specs (https://github.com/ansible/ansible/pull/82671)."
diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py
index 0e0b7631f14..d052f505226 100755
--- a/lib/ansible/cli/doc.py
+++ b/lib/ansible/cli/doc.py
@@ -1339,6 +1339,17 @@ class DocCLI(CLI, RoleMixin):
                     # use empty indent since this affects the start of the yaml doc, not it's keys
                     text.append(DocCLI._indent_lines(DocCLI._dump_yaml({k.upper(): doc[k]}), ''))
 
+            if doc.get('examples', False):
+                text.append('')
+                text.append(_format("EXAMPLES:", 'bold'))
+                if isinstance(doc['examples'], string_types):
+                    text.append(doc.pop('examples').strip())
+                else:
+                    try:
+                        text.append(yaml_dump(doc.pop('examples'), indent=2, default_flow_style=False))
+                    except Exception as e:
+                        raise AnsibleParserError("Unable to parse examples section", orig_exc=e)
+
         return text
 
     @staticmethod
diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/roles/testrole/meta/main.yml b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/roles/testrole/meta/main.yml
index ce7962990df..5ec7177f2c4 100644
--- a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/roles/testrole/meta/main.yml
+++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/roles/testrole/meta/main.yml
@@ -28,3 +28,6 @@ argument_specs:
                 description: altopt1 description
                 type: "int"
                 required: true
+        examples: |-
+          This is an example.
+          It has two lines.
diff --git a/test/integration/targets/ansible-doc/fakecollrole.output b/test/integration/targets/ansible-doc/fakecollrole.output
index b41a35d4d5e..685793aa3d2 100644
--- a/test/integration/targets/ansible-doc/fakecollrole.output
+++ b/test/integration/targets/ansible-doc/fakecollrole.output
@@ -18,3 +18,7 @@ ATTRIBUTES:
           support: full
 
 AUTHOR: Ansible Core (@ansible)
+
+EXAMPLES:
+This is an example.
+It has two lines.