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

changelogs/fragments/80212-ansible-doc-seealso.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "ansible-doc text output - support ``seealso`` plugin record that was added for filter and test plugin documentation (https://github.com/ansible/ansible/pull/80212)."

lib/ansible/cli/doc.py

@@ -1296,6 +1296,20 @@ class DocCLI(CLI, RoleMixin):
                         relative_url = 'collections/%s_module.html' % item['module'].replace('.', '/', 2)
                         text.append(textwrap.fill(DocCLI.tty_ify(get_versioned_doclink(relative_url)),
                                     limit - 6, initial_indent=opt_indent + '   ', subsequent_indent=opt_indent))
+                elif 'plugin' in item and 'plugin_type' in item:
+                    plugin_suffix = ' plugin' if item['plugin_type'] not in ('module', 'role') else ''
+                    text.append(textwrap.fill(DocCLI.tty_ify('%s%s %s' % (item['plugin_type'].title(), plugin_suffix, item['plugin'])),
+                                limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))
+                    description = item.get('description')
+                    if description is None and item['plugin'].startswith('ansible.builtin.'):
+                        description = 'The official documentation on the %s %s%s.' % (item['plugin'], item['plugin_type'], plugin_suffix)
+                    if description is not None:
+                        text.append(textwrap.fill(DocCLI.tty_ify(description),
+                                    limit - 6, initial_indent=opt_indent + '   ', subsequent_indent=opt_indent + '   '))
+                    if item['plugin'].startswith('ansible.builtin.'):
+                        relative_url = 'collections/%s_%s.html' % (item['plugin'].replace('.', '/', 2), item['plugin_type'])
+                        text.append(textwrap.fill(DocCLI.tty_ify(get_versioned_doclink(relative_url)),
+                                    limit - 6, initial_indent=opt_indent + '   ', subsequent_indent=opt_indent))
                 elif 'name' in item and 'link' in item and 'description' in item:
                     text.append(textwrap.fill(DocCLI.tty_ify(item['name']),
                                 limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))

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

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"

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

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"
+            }
+        }
+    }
+}