ansible-doc role arg spec support (#72120)

* Support listing roles in text and JSON

* Change tests for unfrack'd playbook_dir var

These tests were using '/tmp' for testing the setting of the playbook_dir
var. Now that we unfrack that var, MacOS will change this to '/private/tmp'
causing the tests to fail. We can choose a path that does not exist (since
unfrack does not validate existence) so that we can guarantee unfracking
will not change the value.

9 files changed, 142 insertions, 2 deletions

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
new file mode 100644
index 0000000000..5b1b7049d2
--- /dev/null
+++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/roles/testrole/meta/argument_specs.yml
@@ -0,0 +1,22 @@
+---
+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_with_no_argspecs/meta/empty b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/roles/testrole_with_no_argspecs/meta/empty
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/roles/testrole_with_no_argspecs/meta/empty
diff --git a/test/integration/targets/ansible-doc/fakecollrole.output b/test/integration/targets/ansible-doc/fakecollrole.output
new file mode 100644
index 0000000000..fdd6a2dda6
--- /dev/null
+++ b/test/integration/targets/ansible-doc/fakecollrole.output
@@ -0,0 +1,16 @@
+> TESTNS.TESTCOL.TESTROLE    (/ansible/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol)
+
+ENTRY POINT: alternate - testns.testcol.testrole short description for alternate entry point
+
+        Longer description for testns.testcol.testrole alternate entry
+        point.
+
+OPTIONS (= is mandatory):
+
+= altopt1
+        altopt1 description
+
+        type: int
+
+
+AUTHOR: Ansible Core (@ansible)
diff --git a/test/integration/targets/ansible-doc/fakerole.output b/test/integration/targets/ansible-doc/fakerole.output
new file mode 100644
index 0000000000..81db9a63fe
--- /dev/null
+++ b/test/integration/targets/ansible-doc/fakerole.output
@@ -0,0 +1,32 @@
+> TEST_ROLE1    (/ansible/test/integration/targets/ansible-doc/roles/normal_role1)
+
+ENTRY POINT: main - test_role1 from roles subdir
+
+        In to am attended desirous raptures *declared* diverted
+        confined at. Collected instantly remaining up certainly to
+        `necessary' as. Over walk dull into son boy door went new. At
+        or happiness commanded daughters as. Is `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.
+
+OPTIONS (= is mandatory):
+
+= myopt1
+        First option.
+
+        type: str
+
+- myopt2
+        Second option
+        [Default: 8000]
+        type: int
+
+- myopt3
+        Third option.
+        (Choices: choice1, choice2)[Default: (null)]
+        type: str
+
+
+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
new file mode 100644
index 0000000000..6fa9c74cbf
--- /dev/null
+++ b/test/integration/targets/ansible-doc/roles/test_role1/meta/argument_specs.yml
@@ -0,0 +1,33 @@
+---
+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_role2/meta/empty b/test/integration/targets/ansible-doc/roles/test_role2/meta/empty
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/test/integration/targets/ansible-doc/roles/test_role2/meta/empty
diff --git a/test/integration/targets/ansible-doc/runme.sh b/test/integration/targets/ansible-doc/runme.sh
index c4bea83d4c..4d5e915cb6 100755
--- a/test/integration/targets/ansible-doc/runme.sh
+++ b/test/integration/targets/ansible-doc/runme.sh
@@ -14,8 +14,9 @@ unset ANSIBLE_PLAYBOOK_DIR
 cd "$(dirname "$0")"
 
 # test module docs from collection
-current_out="$(ansible-doc --playbook-dir ./ testns.testcol.fakemodule)"
-expected_out="$(cat fakemodule.output)"
+# we use sed to strip the module path from the first line
+current_out="$(ansible-doc --playbook-dir ./ testns.testcol.fakemodule | sed '1 s/\(^> TESTNS\.TESTCOL\.FAKEMODULE\).*(.*)$/\1/')"
+expected_out="$(sed '1 s/\(^> TESTNS\.TESTCOL\.FAKEMODULE\).*(.*)$/\1/' fakemodule.output)"
 test "$current_out" == "$expected_out"
 
 # ensure we do work with valid collection name for list
@@ -45,4 +46,33 @@ do
 	justcol=$(ansible-doc -l -t ${ptype} --playbook-dir ./ testns|wc -l)
 	test "$justcol" -eq 1
 done
+
+#### test role functionality
+
+# Test role text output
+# we use sed to strip the role path from the first line
+current_role_out="$(ansible-doc -t role -r ./roles test_role1 | sed '1 s/\(^> TEST_ROLE1\).*(.*)$/\1/')"
+expected_role_out="$(sed '1 s/\(^> TEST_ROLE1\).*(.*)$/\1/' fakerole.output)"
+test "$current_role_out" == "$expected_role_out"
+
+# Two collection roles are defined, but only 1 has a role arg spec with 2 entry points
+output=$(ansible-doc -t role -l --playbook-dir . testns.testcol | wc -l)
+test "$output" -eq 2
+
+# Include normal roles (no collection filter)
+output=$(ansible-doc -t role -l --playbook-dir . | wc -l)
+test "$output" -eq 3
+
+# Test that a role in the playbook dir with the same name as a role in the
+# 'roles' subdir of the playbook dir does not appear (lower precedence).
+output=$(ansible-doc -t role -l --playbook-dir . | grep -c "test_role1 from roles subdir")
+test "$output" -eq 1
+output=$(ansible-doc -t role -l --playbook-dir . | grep -c "test_role1 from playbook dir" || true)
+test "$output" -eq 0
+
+# Test entry point filter
+current_role_out="$(ansible-doc -t role --playbook-dir . testns.testcol.testrole -e alternate| sed '1 s/\(^> TESTNS\.TESTCOL\.TESTROLE\).*(.*)$/\1/')"
+expected_role_out="$(sed '1 s/\(^> TESTNS\.TESTCOL\.TESTROLE\).*(.*)$/\1/' fakecollrole.output)"
+test "$current_role_out" == "$expected_role_out"
+
 )
diff --git a/test/integration/targets/ansible-doc/test_role1/README.txt b/test/integration/targets/ansible-doc/test_role1/README.txt
new file mode 100644
index 0000000000..98983c8cee
--- /dev/null
+++ b/test/integration/targets/ansible-doc/test_role1/README.txt
@@ -0,0 +1,3 @@
+Test role that exists in the playbook directory so we can validate
+that a role of the same name that exists in the 'roles' subdirectory
+will take precedence over this one.
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
new file mode 100644
index 0000000000..9a35758755
--- /dev/null
+++ b/test/integration/targets/ansible-doc/test_role1/meta/argument_specs.yml
@@ -0,0 +1,4 @@
+---
+main:
+    short_description: test_role1 from playbook dir
+    description: This should not appear in `ansible-doc --list` output.