ansible-doc: restore role attributes (#82678)

* Restore role attributes.

* Add a deprecation warning for role argument specs containing attributes

Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: s-hertel <19572925+s-hertel@users.noreply.github.com>
Co-authored-by: Brian Coca <bcoca@users.noreply.github.com>

changelogs/fragments/82678-role-entrypoint-attributes.yml

@@ -0,0 +1,2 @@
+deprecated_features:
+  - "ansible-doc - role entrypoint attributes are deprecated and eventually will no longer be shown in ansible-doc from ansible-core 2.20 on (https://github.com/ansible/ansible/issues/82639, https://github.com/ansible/ansible/pull/82678)."

lib/ansible/cli/doc.py

@@ -1306,6 +1306,24 @@ class DocCLI(CLI, RoleMixin):
                 text.append(_format("Options", 'bold') + " (%s inicates it is required):" % ("=" if C.ANSIBLE_NOCOLOR else 'red'))
                 DocCLI.add_fields(text, doc.pop('options'), limit, opt_indent)
 
+            if doc.get('attributes', False):
+                display.deprecated(
+                    f'The role {role}\'s argument spec {entry_point} contains the key "attributes", '
+                    'which will not be displayed by ansible-doc in the future. '
+                    'This was unintentionally allowed when plugin attributes were added, '
+                    'but the feature does not map well to role argument specs.',
+                    version='2.20',
+                    collection_name='ansible.builtin',
+                )
+                text.append("")
+                text.append(_format("ATTRIBUTES:", 'bold'))
+                for k in doc['attributes'].keys():
+                    text.append('')
+                    text.append(DocCLI.warp_fill(DocCLI.tty_ify(_format('%s:' % k, 'UNDERLINE')), limit - 6, initial_indent=opt_indent,
+                                                 subsequent_indent=opt_indent))
+                    text.append(DocCLI._indent_lines(DocCLI._dump_yaml(doc['attributes'][k]), opt_indent))
+                del doc['attributes']
+
             # generic elements we will handle identically
             for k in ('author',):
                 if k not in doc:

test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/roles/testrole/meta/main.yml

@@ -19,6 +19,10 @@ argument_specs:
         description:
             - Longer description for testns.testcol.testrole alternate entry point.
         author: Ansible Core (@ansible)
+        attributes:
+            check_mode:
+                description: Can run in check_mode and return changed status prediction without modifying target
+                support: full
         options:
             altopt1:
                 description: altopt1 description

test/integration/targets/ansible-doc/fakecollrole.output

@@ -10,4 +10,11 @@ Options (= inicates it is required):
 = altopt1   altopt1 description
           type: int
 
+ATTRIBUTES:
+
+          `check_mode:`
+          description: Can run in check_mode and return changed status prediction without modifying
+            target
+          support: full
+
 AUTHOR: Ansible Core (@ansible)

test/integration/targets/ansible-doc/fakerole.output

@@ -25,4 +25,12 @@ Options (= inicates it is required):
           default: null
           type: str
 
+ATTRIBUTES:
+
+          `diff_mode:`
+          description: Will return details on what has changed (or possibly needs changing in
+            check_mode), when in diff mode
+          details: Not all modules used support this
+          support: partial
+
 AUTHOR: John Doe (@john), Jane Doe (@jane)

test/integration/targets/ansible-doc/roles/test_role1/meta/argument_specs.yml

@@ -11,7 +11,11 @@ argument_specs:
         author:
           - John Doe (@john)
           - Jane Doe (@jane)
-
+        attributes:
+          diff_mode:
+            description: Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
+            support: partial
+            details: Not all modules used support this
         options:
             myopt1:
                 description: