From 0d866b97f3b81b6e4694625778753728b0a0e29a Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 30 Jun 2020 23:00:32 +0200 Subject: [PATCH 1/2] ansible-doc: include collection name in text output --- .../fragments/ansible-doc-collection-name.yml | 2 ++ lib/ansible/cli/doc.py | 21 +++++++++++-------- .../testcol/plugins/cache/notjsonfile.py | 2 +- .../testcol/plugins/inventory/statichost.py | 2 +- .../testns/testcol/plugins/lookup/noop.py | 2 +- .../testcol/plugins/vars/noop_vars_plugin.py | 2 +- .../targets/ansible-doc/fakemodule.output | 2 +- 7 files changed, 19 insertions(+), 14 deletions(-) create mode 100644 changelogs/fragments/ansible-doc-collection-name.yml diff --git a/changelogs/fragments/ansible-doc-collection-name.yml b/changelogs/fragments/ansible-doc-collection-name.yml new file mode 100644 index 00000000000000..a172cc94349701 --- /dev/null +++ b/changelogs/fragments/ansible-doc-collection-name.yml @@ -0,0 +1,2 @@ +bugfixes: +- "ansible-doc - include the collection name in the text output (https://github.com/ansible/ansible/pull/70401)." \ No newline at end of file diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py index 0572ec9d59c10b..4d1ab1d49876bc 100644 --- a/lib/ansible/cli/doc.py +++ b/lib/ansible/cli/doc.py @@ -69,7 +69,7 @@ class DocCLI(CLI): and it can create a short "snippet" which can be pasted into a playbook. ''' # default ignore list for detailed views - IGNORE = ('module', 'docuri', 'version_added', 'short_description', 'now_date', 'plainexamples', 'returndocs') + IGNORE = ('module', 'docuri', 'version_added', 'short_description', 'now_date', 'plainexamples', 'returndocs', 'collection') def __init__(self, args): @@ -315,26 +315,25 @@ def _get_plugin_doc(plugin, plugin_type, loader, search_paths): raise PluginNotFound('%s was not found in %s' % (plugin, search_paths)) plugin_name, filename = result.plugin_resolved_name, result.plugin_resolved_path - collection_name = 'ansible.builtin' + collection_name = '' if plugin_name.startswith('ansible_collections.'): collection_name = '.'.join(plugin_name.split('.')[1:3]) doc, plainexamples, returndocs, metadata = get_docstring( filename, fragment_loader, verbose=(context.CLIARGS['verbosity'] > 0), - collection_name=collection_name, is_module=(plugin_type == 'module')) + collection_name=collection_name or 'ansible.builtin', is_module=(plugin_type == 'module')) # If the plugin existed but did not have a DOCUMENTATION element and was not removed, it's an error if doc is None: raise ValueError('%s did not contain a DOCUMENTATION attribute' % plugin) doc['filename'] = filename + doc['collection'] = collection_name return doc, plainexamples, returndocs, metadata @staticmethod def format_plugin_doc(plugin, plugin_type, doc, plainexamples, returndocs, metadata): - collection_name = 'ansible.builtin' - if plugin.startswith('ansible_collections.'): - collection_name = '.'.join(plugin.split('.')[1:3]) + collection_name = doc['collection'] # TODO: do we really want this? # add_collection_to_versions_and_dates(doc, '(unknown)', is_module=(plugin_type == 'module')) @@ -363,7 +362,7 @@ def format_plugin_doc(plugin, plugin_type, doc, plainexamples, returndocs, metad text = DocCLI.get_snippet_text(doc) else: try: - text = DocCLI.get_man_text(doc) + text = DocCLI.get_man_text(doc, collection_name) except Exception as e: raise AnsibleError("Unable to retrieve documentation from '%s' due to: %s" % (plugin, to_native(e))) @@ -594,7 +593,7 @@ def add_fields(text, fields, limit, opt_indent, return_values=False, base_indent text.append('') @staticmethod - def get_man_text(doc): + def get_man_text(doc, collection_name=''): # Create a copy so we don't modify the original doc = dict(doc) @@ -604,7 +603,11 @@ def get_man_text(doc): pad = display.columns * 0.20 limit = max(display.columns - int(pad), 70) - text.append("> %s (%s)\n" % (doc.get(context.CLIARGS['type'], doc.get('plugin_type')).upper(), doc.pop('filename'))) + plugin_name = doc.get(context.CLIARGS['type'], doc.get('plugin_type')) + if collection_name: + plugin_name = '%s.%s' % (collection_name, plugin_name) + + text.append("> %s (%s)\n" % (plugin_name.upper(), doc.pop('filename'))) if isinstance(doc['description'], list): desc = " ".join(doc.pop('description')) diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/cache/notjsonfile.py b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/cache/notjsonfile.py index 38ac9aecec9447..ee56f6ee20e286 100644 --- a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/cache/notjsonfile.py +++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/cache/notjsonfile.py @@ -6,7 +6,7 @@ __metaclass__ = type DOCUMENTATION = ''' - cache: testns.testcol.notjsonfile + cache: notjsonfile short_description: JSON formatted files. description: - This cache uses JSON formatted, per host, files saved to the filesystem. diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/inventory/statichost.py b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/inventory/statichost.py index d6ec0269d96699..cbb8f0fb2a5cc3 100644 --- a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/inventory/statichost.py +++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/inventory/statichost.py @@ -5,7 +5,7 @@ __metaclass__ = type DOCUMENTATION = ''' - inventory: testns.testcol.statichost + inventory: statichost short_description: Add a single host description: Add a single host extends_documentation_fragment: diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/lookup/noop.py b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/lookup/noop.py index edcf0839854eaf..daecac5de69846 100644 --- a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/lookup/noop.py +++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/lookup/noop.py @@ -7,7 +7,7 @@ __metaclass__ = type DOCUMENTATION = """ - lookup: testns.testcol.noop + lookup: noop author: Ansible core team short_description: returns input description: diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/vars/noop_vars_plugin.py b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/vars/noop_vars_plugin.py index 2ff181ab3b7239..ccb33b04dd249a 100644 --- a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/vars/noop_vars_plugin.py +++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/vars/noop_vars_plugin.py @@ -2,7 +2,7 @@ __metaclass__ = type DOCUMENTATION = ''' - vars: testns.testcol.noop_vars_plugin + vars: noop_vars_plugin short_description: Do NOT load host and group vars description: don't test loading host and group vars from a collection options: diff --git a/test/integration/targets/ansible-doc/fakemodule.output b/test/integration/targets/ansible-doc/fakemodule.output index a7abc241d46d5b..adc27e08eb82c9 100644 --- a/test/integration/targets/ansible-doc/fakemodule.output +++ b/test/integration/targets/ansible-doc/fakemodule.output @@ -1,4 +1,4 @@ -> FAKEMODULE (./collections/ansible_collections/testns/testcol/plugins/modules/fakemodule.py) +> TESTNS.TESTCOL.FAKEMODULE (./collections/ansible_collections/testns/testcol/plugins/modules/fakemodule.py) this is a fake module From b7c62710d1a91ad231d316a0aeee6462bf987660 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Fri, 10 Jul 2020 21:24:43 +0200 Subject: [PATCH 2/2] Be more careful to not accidentally pass ansible.builtin for user-supplied modules. --- lib/ansible/cli/doc.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py index 4d1ab1d49876bc..a1e74a4d0335ca 100644 --- a/lib/ansible/cli/doc.py +++ b/lib/ansible/cli/doc.py @@ -272,7 +272,7 @@ def get_plugin_metadata(plugin_type, plugin_name): if filename is None: raise AnsibleError("unable to load {0} plugin named {1} ".format(plugin_type, plugin_name)) - collection_name = 'ansible.builtin' + collection_name = '' if plugin_name.startswith('ansible_collections.'): collection_name = '.'.join(plugin_name.split('.')[1:3]) @@ -321,7 +321,7 @@ def _get_plugin_doc(plugin, plugin_type, loader, search_paths): doc, plainexamples, returndocs, metadata = get_docstring( filename, fragment_loader, verbose=(context.CLIARGS['verbosity'] > 0), - collection_name=collection_name or 'ansible.builtin', is_module=(plugin_type == 'module')) + collection_name=collection_name, is_module=(plugin_type == 'module')) # If the plugin existed but did not have a DOCUMENTATION element and was not removed, it's an error if doc is None: