From 3a18ef7159e794a83ff58c8a5e5c252301551181 Mon Sep 17 00:00:00 2001 From: David Shrewsbury Date: Mon, 14 Dec 2020 12:05:40 -0500 Subject: [PATCH] Change role argspec file used by ansible-doc (#72927) * Change role argspec file used by ansible-doc This changes the file used for role argument specs from meta/argument_specs.yml to meta/main.yml. The argument specs are expected to be in that file under the top-level entry of `argument_spec`. * Switch to argument_specs --- lib/ansible/cli/doc.py | 13 +++++-- .../roles/testrole/meta/argument_specs.yml | 22 ----------- .../testcol/roles/testrole/meta/main.yml | 26 +++++++++++++ .../roles/test_role1/meta/argument_specs.yml | 33 ----------------- .../roles/test_role1/meta/main.yml | 37 +++++++++++++++++++ .../test_role1/meta/argument_specs.yml | 4 -- .../ansible-doc/test_role1/meta/main.yml | 8 ++++ 7 files changed, 80 insertions(+), 63 deletions(-) delete mode 100644 test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/roles/testrole/meta/argument_specs.yml create mode 100644 test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/roles/testrole/meta/main.yml delete mode 100644 test/integration/targets/ansible-doc/roles/test_role1/meta/argument_specs.yml create mode 100644 test/integration/targets/ansible-doc/roles/test_role1/meta/main.yml delete mode 100644 test/integration/targets/ansible-doc/test_role1/meta/argument_specs.yml create mode 100644 test/integration/targets/ansible-doc/test_role1/meta/main.yml diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py index 336b18aad96..a217eddb574 100644 --- a/lib/ansible/cli/doc.py +++ b/lib/ansible/cli/doc.py @@ -78,7 +78,7 @@ class RoleMixin(object): Note: The methods for actual display of role data are not present here. """ - ROLE_ARGSPEC_FILE = 'argument_specs.yml' + ROLE_ARGSPEC_FILE = 'main.yml' def _load_argspec(self, role_name, collection_path=None, role_path=None): if collection_path: @@ -90,13 +90,16 @@ class RoleMixin(object): try: with open(path, 'r') as f: - return from_yaml(f.read(), file_name=path) + data = from_yaml(f.read(), file_name=path) + return data.get('argument_specs', {}) except (IOError, OSError) as e: raise AnsibleParserError("An error occurred while trying to read the file '%s': %s" % (path, to_native(e)), orig_exc=e) def _find_all_normal_roles(self, role_paths, name_filters=None): """Find all non-collection roles that have an argument spec file. + Note that argument specs do not actually need to exist within the spec file. + :param role_paths: A tuple of one or more role paths. When a role with the same name is found in multiple paths, only the first-found role is returned. :param name_filters: A tuple of one or more role names used to filter the results. @@ -108,7 +111,7 @@ class RoleMixin(object): for path in role_paths: if not os.path.isdir(path): continue - # Check each subdir for a meta/argument_specs.yml file + # Check each subdir for a meta/main.yml file for entry in os.listdir(path): role_path = os.path.join(path, entry) full_path = os.path.join(role_path, 'meta', self.ROLE_ARGSPEC_FILE) @@ -120,7 +123,9 @@ class RoleMixin(object): return found def _find_all_collection_roles(self, name_filters=None, collection_filter=None): - """Find all collection roles with an argument spec. + """Find all collection roles with an argument spec file. + + Note that argument specs do not actually need to exist within the spec file. :param name_filters: A tuple of one or more role names used to filter the results. These might be fully qualified with the collection name (e.g., community.general.roleA) diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/roles/testrole/meta/argument_specs.yml b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/roles/testrole/meta/argument_specs.yml deleted file mode 100644 index 5b1b7049d20..00000000000 --- a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/roles/testrole/meta/argument_specs.yml +++ /dev/null @@ -1,22 +0,0 @@ ---- -main: - short_description: testns.testcol.testrole short description for main entry point - description: - - Longer description for testns.testcol.testrole main entry point. - author: Ansible Core (@ansible) - options: - opt1: - description: opt1 description - type: "str" - required: true - -alternate: - short_description: testns.testcol.testrole short description for alternate entry point - description: - - Longer description for testns.testcol.testrole alternate entry point. - author: Ansible Core (@ansible) - options: - altopt1: - description: altopt1 description - type: "int" - required: true 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 new file mode 100644 index 00000000000..bc6af698b89 --- /dev/null +++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/roles/testrole/meta/main.yml @@ -0,0 +1,26 @@ +--- +dependencies: +galaxy_info: + +argument_specs: + main: + short_description: testns.testcol.testrole short description for main entry point + description: + - Longer description for testns.testcol.testrole main entry point. + author: Ansible Core (@ansible) + options: + opt1: + description: opt1 description + type: "str" + required: true + + alternate: + short_description: testns.testcol.testrole short description for alternate entry point + description: + - Longer description for testns.testcol.testrole alternate entry point. + author: Ansible Core (@ansible) + options: + altopt1: + description: altopt1 description + type: "int" + required: true 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 deleted file mode 100644 index 6fa9c74cbf1..00000000000 --- a/test/integration/targets/ansible-doc/roles/test_role1/meta/argument_specs.yml +++ /dev/null @@ -1,33 +0,0 @@ ---- -main: - short_description: test_role1 from roles subdir - description: - - In to am attended desirous raptures B(declared) diverted confined at. Collected instantly remaining - up certainly to C(necessary) as. Over walk dull into son boy door went new. - - At or happiness commanded daughters as. Is I(handsome) an declared at received in extended vicinity - subjects. Into miss on he over been late pain an. Only week bore boy what fat case left use. Match round - scale now style far times. Your me past an much. - author: - - John Doe (@john) - - Jane Doe (@jane) - - options: - myopt1: - description: - - First option. - type: "str" - required: true - - myopt2: - description: - - Second option - type: "int" - default: 8000 - - myopt3: - description: - - Third option. - type: "str" - choices: - - choice1 - - choice2 diff --git a/test/integration/targets/ansible-doc/roles/test_role1/meta/main.yml b/test/integration/targets/ansible-doc/roles/test_role1/meta/main.yml new file mode 100644 index 00000000000..9e6daeb2be9 --- /dev/null +++ b/test/integration/targets/ansible-doc/roles/test_role1/meta/main.yml @@ -0,0 +1,37 @@ +--- +dependencies: +galaxy_info: + +argument_specs: + main: + short_description: test_role1 from roles subdir + description: + - In to am attended desirous raptures B(declared) diverted confined at. Collected instantly remaining + up certainly to C(necessary) as. Over walk dull into son boy door went new. + - At or happiness commanded daughters as. Is I(handsome) an declared at received in extended vicinity + subjects. Into miss on he over been late pain an. Only week bore boy what fat case left use. Match round + scale now style far times. Your me past an much. + author: + - John Doe (@john) + - Jane Doe (@jane) + + options: + myopt1: + description: + - First option. + type: "str" + required: true + + myopt2: + description: + - Second option + type: "int" + default: 8000 + + myopt3: + description: + - Third option. + type: "str" + choices: + - choice1 + - choice2 diff --git a/test/integration/targets/ansible-doc/test_role1/meta/argument_specs.yml b/test/integration/targets/ansible-doc/test_role1/meta/argument_specs.yml deleted file mode 100644 index 9a357587557..00000000000 --- a/test/integration/targets/ansible-doc/test_role1/meta/argument_specs.yml +++ /dev/null @@ -1,4 +0,0 @@ ---- -main: - short_description: test_role1 from playbook dir - description: This should not appear in `ansible-doc --list` output. diff --git a/test/integration/targets/ansible-doc/test_role1/meta/main.yml b/test/integration/targets/ansible-doc/test_role1/meta/main.yml new file mode 100644 index 00000000000..4f7abcc8dc9 --- /dev/null +++ b/test/integration/targets/ansible-doc/test_role1/meta/main.yml @@ -0,0 +1,8 @@ +--- +dependencies: +galaxy_info: + +argument_specs: + main: + short_description: test_role1 from playbook dir + description: This should not appear in `ansible-doc --list` output.