[2.14] ansible-doc: fix broken seealso links in text output (#80285)

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

* Fix broken URLs.

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

(cherry picked from commit fafb23094e)

* Fix URL processing. (#80295)

(cherry picked from commit 086ae42209)

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

@@ -1241,10 +1241,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/fix-urls.py

@@ -0,0 +1,15 @@
+"""Unwrap URLs to docs.ansible.com and remove version"""
+
+import re
+import sys
+
+
+def main():
+    data = sys.stdin.read()
+    data = re.sub('(https://docs\\.ansible\\.com/[^ ]+)\n +([^ ]+)\n', '\\1\\2\n', data, flags=re.MULTILINE)
+    data = re.sub('https://docs\\.ansible\\.com/ansible(|-core)/(?:[^/]+)/', 'https://docs.ansible.com/ansible\\1/devel/', data)
+    sys.stdout.write(data)
+
+
+if __name__ == '__main__':
+    main()

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

@@ -65,6 +65,25 @@ 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/collections/ansible/builtin/ping_module.html
+      * Module ansible.builtin.uri
+           Use this to fetch an URI
+           https://docs.ansible.com/ansible-core/devel/collections/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

@@ -19,8 +19,8 @@ current_out="$(ansible-doc --playbook-dir ./ testns.testcol.fakemodule | sed '1
 expected_out="$(sed '1 s/\(^> TESTNS\.TESTCOL\.FAKEMODULE\).*(.*)$/\1/' fakemodule.output)"
 test "$current_out" == "$expected_out"
 
-# 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 fix-urls.py to unbreak and replace URLs from stable-X branches
+current_out="$(ansible-doc --playbook-dir ./ testns.testcol.randommodule | sed '1 s/\(^> TESTNS\.TESTCOL\.RANDOMMODULE\).*(.*)$/\1/' | python fix-urls.py)"
 expected_out="$(sed '1 s/\(^> TESTNS\.TESTCOL\.RANDOMMODULE\).*(.*)$/\1/' randommodule-text.output)"
 test "$current_out" == "$expected_out"