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
This commit is contained in:
David Shrewsbury 2020-12-14 12:05:40 -05:00 committed by GitHub
parent 83fb24b923
commit 3a18ef7159
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 80 additions and 63 deletions

View file

@ -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)

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -1,4 +0,0 @@
---
main:
short_description: test_role1 from playbook dir
description: This should not appear in `ansible-doc --list` output.

View file

@ -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.