ansible-doc: include collection name in text output (#70401)

* ansible-doc: include collection name in text output

* Be more careful to not accidentally pass ansible.builtin for user-supplied modules.

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)."

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):
 
@@ -272,7 +272,7 @@ class DocCLI(CLI):
         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])
 
@@ -315,7 +315,7 @@ class DocCLI(CLI):
             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])
 
@@ -328,13 +328,12 @@ class DocCLI(CLI):
             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 @@ class DocCLI(CLI):
             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)))
 
@@ -596,7 +595,7 @@ class DocCLI(CLI):
                 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)
 
@@ -606,7 +605,11 @@ class DocCLI(CLI):
         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'))

test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/cache/notjsonfile.py

@@ -6,7 +6,7 @@ from __future__ import (absolute_import, division, print_function)
 __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.

test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/inventory/statichost.py

@@ -5,7 +5,7 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 DOCUMENTATION = '''
-    inventory: testns.testcol.statichost
+    inventory: statichost
     short_description: Add a single host
     description: Add a single host
     extends_documentation_fragment:

test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/lookup/noop.py

@@ -7,7 +7,7 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 DOCUMENTATION = """
-    lookup: testns.testcol.noop
+    lookup: noop
     author: Ansible core team
     short_description: returns input
     description:

test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/vars/noop_vars_plugin.py

@@ -2,7 +2,7 @@ from __future__ import (absolute_import, division, print_function)
 __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:

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