From 11d69e065f46594f53f360b38aba80c1d89b2830 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 21 Mar 2024 22:06:15 +0100 Subject: [PATCH] ansible-doc: restore role attributes (#82678) * Restore role attributes. * Add a deprecation warning for role argument specs containing attributes Co-authored-by: Felix Fontein Co-authored-by: s-hertel <19572925+s-hertel@users.noreply.github.com> Co-authored-by: Brian Coca --- .../82678-role-entrypoint-attributes.yml | 2 ++ lib/ansible/cli/doc.py | 18 ++++++++++++++++++ .../testcol/roles/testrole/meta/main.yml | 4 ++++ .../targets/ansible-doc/fakecollrole.output | 7 +++++++ .../targets/ansible-doc/fakerole.output | 8 ++++++++ .../roles/test_role1/meta/argument_specs.yml | 6 +++++- 6 files changed, 44 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/82678-role-entrypoint-attributes.yml diff --git a/changelogs/fragments/82678-role-entrypoint-attributes.yml b/changelogs/fragments/82678-role-entrypoint-attributes.yml new file mode 100644 index 00000000000..51ba5782fd5 --- /dev/null +++ b/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)." diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py index 8d07391d4f0..16033f8e112 100755 --- a/lib/ansible/cli/doc.py +++ b/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: 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 bc6af698b89..ce7962990df 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 @@ -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 diff --git a/test/integration/targets/ansible-doc/fakecollrole.output b/test/integration/targets/ansible-doc/fakecollrole.output index 6df323ce7a3..b41a35d4d5e 100644 --- a/test/integration/targets/ansible-doc/fakecollrole.output +++ b/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) diff --git a/test/integration/targets/ansible-doc/fakerole.output b/test/integration/targets/ansible-doc/fakerole.output index f713c1959ec..0e82b7f9de4 100644 --- a/test/integration/targets/ansible-doc/fakerole.output +++ b/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) diff --git a/test/integration/targets/ansible-doc/roles/test_role1/meta/argument_specs.yml b/test/integration/targets/ansible-doc/roles/test_role1/meta/argument_specs.yml index 0315a1fd125..42857cd7ff1 100644 --- a/test/integration/targets/ansible-doc/roles/test_role1/meta/argument_specs.yml +++ b/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: