Show examples in role entrypoint argument specs. (#82671)

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)."

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

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.

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.