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

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

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

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

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

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

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

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

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

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

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.