better information for user from inventory plugins (#46766)

* better information for user from inventory plugins

 - use foreman as example

changelogs/fragments/inv_fixes.yml

@@ -0,0 +1,2 @@
+bugfixes:
+    - Give user better error messages and more information on verbose about inventory plugin behaviour

lib/ansible/inventory/manager.py

@@ -278,7 +278,7 @@ class InventoryManager(object):
                         display.debug('%s failed to parse %s' % (plugin_name, source))
                         failures.append({'src': source, 'plugin': plugin_name, 'exc': AnsibleError(e)})
                 else:
-                    display.debug('%s did not meet %s requirements' % (source, plugin_name))
+                    display.v('%s did not meet %s requirements, check plugin documentation if this is unexpected' % (source, plugin_name))
             else:
                 if not parsed and failures:
                     # only if no plugin processed files should we show errors.

lib/ansible/plugins/inventory/__init__.py

@@ -170,8 +170,13 @@ class BaseInventoryPlugin(AnsiblePlugin):
                  So only call this base class if you expect it to be a file.
         '''
 
+        valid = False
         b_path = to_bytes(path, errors='surrogate_or_strict')
-        return (os.path.exists(b_path) and os.access(b_path, os.R_OK))
+        if (os.path.exists(b_path) and os.access(b_path, os.R_OK)):
+            valid = True
+        else:
+            self.display.vvv('Skipping due to inventory source not existing or not being readable by the current user')
+        return valid
 
     def _populate_host_vars(self, hosts, variables, group=None, port=None):
         if not isinstance(variables, Mapping):

lib/ansible/plugins/inventory/foreman.py

@@ -14,7 +14,7 @@ DOCUMENTATION = '''
         - requests >= 1.1
     description:
         - Get inventory hosts from the foreman service.
-        - "Uses a configuration file as an inventory source, it must end in foreman.yml or foreman.yaml and has a ``plugin: foreman`` entry."
+        - "Uses a configuration file as an inventory source, it must end in ``.foreman.yml`` or ``.foreman.yaml`` and has a ``plugin: foreman`` entry."
     extends_documentation_fragment:
         - inventory_cache
     options:
@@ -29,7 +29,7 @@ DOCUMENTATION = '''
         description: foreman authentication user
         required: True
       password:
-        description: forman authentication password
+        description: foreman authentication password
         required: True
       validate_certs:
         description: verify SSL certificate if using https
@@ -102,6 +102,8 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
         if super(InventoryModule, self).verify_file(path):
             if path.endswith(('foreman.yaml', 'foreman.yml')):
                 valid = True
+            else:
+                self.display.vvv('Skipping due to inventory source not ending in "foreman.yaml" nor "foreman.yml"')
         return valid
 
     def _get_session(self):