ansible-doc: fix broken seealso links in text output (#80280)

* Fix broken URLs.

* Also remove auto-generated description for modules outside ansible.builtin.

changelogs/fragments/80280-ansible-doc-seealso-urls.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - "ansible-doc - stop generating wrong module URLs for module see-alsos. The URLs for modules in ansible.builtin do now work, and URLs for modules outside ansible.builtin are no longer added (https://github.com/ansible/ansible/pull/80280)."

lib/ansible/cli/doc.py

@@ -1286,10 +1286,16 @@ class DocCLI(CLI, RoleMixin):
                 if 'module' in item:
                     text.append(textwrap.fill(DocCLI.tty_ify('Module %s' % item['module']),
                                 limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))
-                    description = item.get('description', 'The official documentation on the %s module.' % item['module'])
-                    text.append(textwrap.fill(DocCLI.tty_ify(description), limit - 6, initial_indent=opt_indent + '   ', subsequent_indent=opt_indent + '   '))
-                    text.append(textwrap.fill(DocCLI.tty_ify(get_versioned_doclink('modules/%s_module.html' % item['module'])),
-                                limit - 6, initial_indent=opt_indent + '   ', subsequent_indent=opt_indent))
+                    description = item.get('description')
+                    if description is None and item['module'].startswith('ansible.builtin.'):
+                        description = 'The official documentation on the %s module.' % item['module']
+                    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['module'].startswith('ansible.builtin.'):
+                        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 '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/modules/randommodule.py

@@ -48,6 +48,18 @@ options:
                 version: '2.0.0'
 extends_documentation_fragment:
     - testns.testcol2.module
+seealso:
+    - module: ansible.builtin.ping
+    - module: ansible.builtin.uri
+      description: Use this to fetch an URI
+    - module: testns.testcol.test
+    - module: testns.testcol.fakemodule
+      description: A fake module
+    - link: https://docs.ansible.com
+      name: Ansible docsite
+      description: See also the Ansible docsite.
+    - ref: foo_bar
+      description: Some foo bar.
 '''
 
 EXAMPLES = '''

test/integration/targets/ansible-doc/randommodule-text.output

@@ -68,6 +68,28 @@ OPTIONS (= is mandatory):
         type: str
 
 
+SEE ALSO:
+      * Module ansible.builtin.ping
+           The official documentation on the
+           ansible.builtin.ping module.
+           https://docs.ansible.com/ansible-core/devel/collectio
+        ns/ansible/builtin/ping_module.html
+      * Module ansible.builtin.uri
+           Use this to fetch an URI
+           https://docs.ansible.com/ansible-core/devel/collectio
+        ns/ansible/builtin/uri_module.html
+      * Module testns.testcol.test
+      * Module testns.testcol.fakemodule
+           A fake module
+      * 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
+
+
 AUTHOR: Ansible Core Team
 
 EXAMPLES:

test/integration/targets/ansible-doc/randommodule.output

@@ -70,6 +70,31 @@
                     "type": "str"
                 }
             },
+            "seealso": [
+                {
+                    "module": "ansible.builtin.ping"
+                },
+                {
+                    "description": "Use this to fetch an URI",
+                    "module": "ansible.builtin.uri"
+                },
+                {
+                    "module": "testns.testcol.test"
+                },
+                {
+                    "description": "A fake module",
+                    "module": "testns.testcol.fakemodule"
+                },
+                {
+                    "description": "See also the Ansible docsite.",
+                    "link": "https://docs.ansible.com",
+                    "name": "Ansible docsite"
+                },
+                {
+                    "description": "Some foo bar.",
+                    "ref": "foo_bar"
+                }
+            ],
             "short_description": "A random module",
             "version_added": "1.0.0",
             "version_added_collection": "testns.testcol"

test/integration/targets/ansible-doc/runme.sh

@@ -43,8 +43,8 @@ expected_out="$(sed '1 s/\(^> TESTNS\.TESTCOL\.FAKEMODULE\).*(.*)$/\1/' fakemodu
 test "$current_out" == "$expected_out"
 
 echo "test randommodule docs from collection"
-# we use sed to strip the module path from the first line
-current_out="$(ansible-doc --playbook-dir ./ testns.testcol.randommodule | sed '1 s/\(^> TESTNS\.TESTCOL\.RANDOMMODULE\).*(.*)$/\1/')"
+# we use sed to strip the plugin path from the first line, and remove versions from URLs when this is run from stable-X branches
+current_out="$(ansible-doc --playbook-dir ./ testns.testcol.randommodule | sed '1 s/\(^> TESTNS\.TESTCOL\.RANDOMMODULE\).*(.*)$/\1/' | sed 's/https:\/\/docs.ansible.com\/ansible-core\/[^\/]+\//https:\/\/docs.ansible.com\/ansible-core\/devel\//g')"
 expected_out="$(sed '1 s/\(^> TESTNS\.TESTCOL\.RANDOMMODULE\).*(.*)$/\1/' randommodule-text.output)"
 test "$current_out" == "$expected_out"