From fafb23094e77a619066a92a7fa99a7045292e473 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 23 Mar 2023 18:28:05 +0100 Subject: ansible-doc: fix broken seealso links in text output (#80280) * Fix broken URLs. * Also remove auto-generated description for modules outside ansible.builtin. --- .../fragments/80280-ansible-doc-seealso-urls.yml | 2 ++ lib/ansible/cli/doc.py | 14 ++++++++---- .../testns/testcol/plugins/modules/randommodule.py | 12 +++++++++++ .../targets/ansible-doc/randommodule-text.output | 22 +++++++++++++++++++ .../targets/ansible-doc/randommodule.output | 25 ++++++++++++++++++++++ test/integration/targets/ansible-doc/runme.sh | 4 ++-- 6 files changed, 73 insertions(+), 6 deletions(-) create mode 100644 changelogs/fragments/80280-ansible-doc-seealso-urls.yml diff --git a/changelogs/fragments/80280-ansible-doc-seealso-urls.yml b/changelogs/fragments/80280-ansible-doc-seealso-urls.yml new file mode 100644 index 0000000000..882fd08940 --- /dev/null +++ b/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)." diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py index dfe27f64b3..54b328074f 100755 --- a/lib/ansible/cli/doc.py +++ b/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)) diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/modules/randommodule.py b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/modules/randommodule.py index 9d59a7bbf2..12a3f0a927 100644 --- a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/modules/randommodule.py +++ b/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 = ''' diff --git a/test/integration/targets/ansible-doc/randommodule-text.output b/test/integration/targets/ansible-doc/randommodule-text.output index a9c426656d..08eae65e9b 100644 --- a/test/integration/targets/ansible-doc/randommodule-text.output +++ b/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: diff --git a/test/integration/targets/ansible-doc/randommodule.output b/test/integration/targets/ansible-doc/randommodule.output index c882d4b368..d97dde8bdc 100644 --- a/test/integration/targets/ansible-doc/randommodule.output +++ b/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" diff --git a/test/integration/targets/ansible-doc/runme.sh b/test/integration/targets/ansible-doc/runme.sh index 15da78f0ce..62f7b26d8e 100755 --- a/test/integration/targets/ansible-doc/runme.sh +++ b/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" -- cgit v1.2.1