From 08297ce0dbde9668841dc0949bf6445b75bea7f4 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 28 Mar 2023 20:06:33 +0200 Subject: [PATCH] [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 fafb23094e77a619066a92a7fa99a7045292e473) * Fix URL processing. (#80295) (cherry picked from commit 086ae4220957cdb66eee8aa060c151a071f3b9bd) --- .../80280-ansible-doc-seealso-urls.yml | 2 ++ lib/ansible/cli/doc.py | 14 ++++++++--- .../testcol/plugins/modules/randommodule.py | 12 +++++++++ .../targets/ansible-doc/fix-urls.py | 15 +++++++++++ .../ansible-doc/randommodule-text.output | 19 ++++++++++++++ .../targets/ansible-doc/randommodule.output | 25 +++++++++++++++++++ test/integration/targets/ansible-doc/runme.sh | 4 +-- 7 files changed, 85 insertions(+), 6 deletions(-) create mode 100644 changelogs/fragments/80280-ansible-doc-seealso-urls.yml create mode 100644 test/integration/targets/ansible-doc/fix-urls.py 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 00000000000..882fd089400 --- /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 803653038aa..9f560bcbc6d 100755 --- a/lib/ansible/cli/doc.py +++ b/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)) 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 f251a69f0ea..79b7a704a1b 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/fix-urls.py b/test/integration/targets/ansible-doc/fix-urls.py new file mode 100644 index 00000000000..1379a4e4a0b --- /dev/null +++ b/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() diff --git a/test/integration/targets/ansible-doc/randommodule-text.output b/test/integration/targets/ansible-doc/randommodule-text.output index 51d7930a079..602d66ec9f5 100644 --- a/test/integration/targets/ansible-doc/randommodule-text.output +++ b/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: diff --git a/test/integration/targets/ansible-doc/randommodule.output b/test/integration/targets/ansible-doc/randommodule.output index 25f46c36222..cf0360003aa 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 887d3c417ee..f51fa8a432c 100755 --- a/test/integration/targets/ansible-doc/runme.sh +++ b/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"