Add support for plugin field in seealso. (#80212)

4 files changed, 145 insertions, 0 deletions

diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/test/yolo.yml b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/test/yolo.yml
index cc60945ec7..ebfea2afb8 100644
--- a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/test/yolo.yml
+++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/test/yolo.yml
@@ -8,6 +8,25 @@ DOCUMENTATION:
       description: does not matter
       type: raw
       required: true
+  seealso:
+    - module: ansible.builtin.test
+    - module: testns.testcol.fakemodule
+      description: A fake module
+    - plugin: testns.testcol.noop
+      plugin_type: lookup
+    - plugin: testns.testcol.grouped
+      plugin_type: filter
+      description: A grouped filter.
+    - plugin: ansible.builtin.combine
+      plugin_type: filter
+    - plugin: ansible.builtin.file
+      plugin_type: lookup
+      description: Read a file on the controller.
+    - link: https://docs.ansible.com
+      name: Ansible docsite
+      description: See also the Ansible docsite.
+    - ref: foo_bar
+      description: Some foo bar.
 
 EXAMPLES: |
   {{ 'anything' is yolo }}
diff --git a/test/integration/targets/ansible-doc/runme.sh b/test/integration/targets/ansible-doc/runme.sh
index 62f7b26d8e..8fde3e053b 100755
--- a/test/integration/targets/ansible-doc/runme.sh
+++ b/test/integration/targets/ansible-doc/runme.sh
@@ -48,6 +48,12 @@ current_out="$(ansible-doc --playbook-dir ./ testns.testcol.randommodule | sed '
 expected_out="$(sed '1 s/\(^> TESTNS\.TESTCOL\.RANDOMMODULE\).*(.*)$/\1/' randommodule-text.output)"
 test "$current_out" == "$expected_out"
 
+echo "test yolo filter docs from collection"
+# we use sed to strip the plugin path from the first line
+current_out="$(ansible-doc --playbook-dir ./ testns.testcol.yolo --type test | sed '1 s/\(^> TESTNS\.TESTCOL\.YOLO\).*(.*)$/\1/' | sed 's/https:\/\/docs.ansible.com\/ansible-core\/[^\/]+\//https:\/\/docs.ansible.com\/ansible-core\/devel\//g')"
+expected_out="$(sed '1 s/\(^> TESTNS\.TESTCOL\.YOLO\).*(.*)$/\1/' yolo-text.output)"
+test "$current_out" == "$expected_out"
+
 echo "ensure we do work with valid collection name for list"
 ansible-doc --list testns.testcol --playbook-dir ./ 2>&1 | grep $GREP_OPTS -v "Invalid collection name"
 
@@ -135,6 +141,11 @@ current_out="$(ansible-doc --json --playbook-dir ./ testns.testcol.randommodule
 expected_out="$(sed 's/ *"filename": "[^"]*",$//' randommodule.output)"
 test "$current_out" == "$expected_out"
 
+echo "testing json output 2"
+current_out="$(ansible-doc --json --playbook-dir ./ testns.testcol.yolo --type test | sed 's/ *$//' | sed 's/ *"filename": "[^"]*",$//')"
+expected_out="$(sed 's/ *"filename": "[^"]*",$//' yolo.output)"
+test "$current_out" == "$expected_out"
+
 current_out="$(ansible-doc --json --playbook-dir ./ -t cache testns.testcol.notjsonfile | sed 's/ *$//' | sed 's/ *"filename": "[^"]*",$//')"
 expected_out="$(sed 's/ *"filename": "[^"]*",$//' notjsonfile.output)"
 test "$current_out" == "$expected_out"
diff --git a/test/integration/targets/ansible-doc/yolo-text.output b/test/integration/targets/ansible-doc/yolo-text.output
new file mode 100644
index 0000000000..5d0570d974
--- /dev/null
+++ b/test/integration/targets/ansible-doc/yolo-text.output
@@ -0,0 +1,51 @@
+> TESTNS.TESTCOL.YOLO    (./collections/ansible_collections/testns/testcol/plugins/test/yolo.yml)
+
+        This is always true
+
+OPTIONS (= is mandatory):
+
+= _input
+        does not matter
+        type: raw
+
+
+SEE ALSO:
+      * Module ansible.builtin.test
+           The official documentation on the
+           ansible.builtin.test module.
+           https://docs.ansible.com/ansible-core/devel/collectio
+        ns/ansible/builtin/test_module.html
+      * Module testns.testcol.fakemodule
+           A fake module
+      * Lookup plugin testns.testcol.noop
+      * Filter plugin testns.testcol.grouped
+           A grouped filter.
+      * Filter plugin ansible.builtin.combine
+           The official documentation on the
+           ansible.builtin.combine filter plugin.
+           https://docs.ansible.com/ansible-core/devel/collectio
+        ns/ansible/builtin/combine_filter.html
+      * Lookup plugin ansible.builtin.file
+           Read a file on the controller.
+           https://docs.ansible.com/ansible-core/devel/collectio
+        ns/ansible/builtin/file_lookup.html
+      * Ansible docsite
+           See also the Ansible docsite.
+           https://docs.ansible.com
+      * Ansible documentation [foo_bar]
+           Some foo bar.
+           https://docs.ansible.com/ansible-
+           core/devel/#stq=foo_bar&stp=1
+
+
+NAME: yolo
+
+EXAMPLES:
+
+{{ 'anything' is yolo }}
+
+
+RETURN VALUES:
+- output
+        always true
+        type: boolean
diff --git a/test/integration/targets/ansible-doc/yolo.output b/test/integration/targets/ansible-doc/yolo.output
new file mode 100644
index 0000000000..b54cc2de53
--- /dev/null
+++ b/test/integration/targets/ansible-doc/yolo.output
@@ -0,0 +1,64 @@
+{
+    "testns.testcol.yolo": {
+        "doc": {
+            "collection": "testns.testcol",
+            "description": [
+                "This is always true"
+            ],
+            "filename": "./collections/ansible_collections/testns/testcol/plugins/test/yolo.yml",
+            "name": "yolo",
+            "options": {
+                "_input": {
+                    "description": "does not matter",
+                    "required": true,
+                    "type": "raw"
+                }
+            },
+            "seealso": [
+                {
+                    "module": "ansible.builtin.test"
+                },
+                {
+                    "description": "A fake module",
+                    "module": "testns.testcol.fakemodule"
+                },
+                {
+                    "plugin": "testns.testcol.noop",
+                    "plugin_type": "lookup"
+                },
+                {
+                    "description": "A grouped filter.",
+                    "plugin": "testns.testcol.grouped",
+                    "plugin_type": "filter"
+                },
+                {
+                    "plugin": "ansible.builtin.combine",
+                    "plugin_type": "filter"
+                },
+                {
+                    "description": "Read a file on the controller.",
+                    "plugin": "ansible.builtin.file",
+                    "plugin_type": "lookup"
+                },
+                {
+                    "description": "See also the Ansible docsite.",
+                    "link": "https://docs.ansible.com",
+                    "name": "Ansible docsite"
+                },
+                {
+                    "description": "Some foo bar.",
+                    "ref": "foo_bar"
+                }
+            ],
+            "short_description": "you only live once"
+        },
+        "examples": "{{ 'anything' is yolo }}\n",
+        "metadata": null,
+        "return": {
+            "output": {
+                "description": "always true",
+                "type": "boolean"
+            }
+        }
+    }
+}