Add some documentation about plugins in collections (#62465)

* Add some documentation about using plugins in collections

- FQCN requirements
- Sharing code in collections
- Limitations with inventory caching

docs/docsite/rst/dev_guide/developing_collections.rst

@@ -77,7 +77,9 @@ The ``ansible-doc`` command requires the fully qualified collection name (FQCN)
 plugins directory
 ------------------
 
-Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by any other plugin by using their FQCN. This is a way to distribute modules, lookups, filters, and so on, without having to import a role in every play.
+Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by most plugins by using their FQCN. This is a way to distribute modules, lookups, filters, and so on, without having to import a role in every play.
+
+Vars plugins are unsupported in collections. Cache plugins may be used in collections for fact caching, but are not supported for inventory plugins.
 
 module_utils
 ^^^^^^^^^^^^
@@ -114,6 +116,11 @@ In the Python example the ``module_util`` in question is called ``qradar`` such
         not_rest_data_keys=['state']
     )
 
+Note that importing something from an ``__init__.py`` file requires using the file name:
+
+.. code-block:: python
+
+    from ansible_collections.namespace.collection_name.plugins.callback.__init__ import CustomBaseClass
 
 In the PowerShell example the ``module_util`` in question is called ``hyperv`` such that the FCQN is
 ``ansible_example.community.plugins.module_utils.hyperv``:

docs/docsite/rst/dev_guide/developing_inventory.rst

@@ -74,6 +74,8 @@ The first thing you want to do is use the base class:
 
         NAME = 'myplugin'  # used internally by Ansible, it should match the file name but not required
 
+If the inventory plugin is in a collection the NAME should be in the format of 'namespace.collection_name.myplugin'.
+
 This class has a couple of methods each plugin should implement and a few helpers for parsing the inventory source and updating the inventory.
 
 After you have the basic plugin working you might want to to incorporate other features by adding more base classes:

docs/docsite/rst/dev_guide/developing_plugins.rst

@@ -150,7 +150,7 @@ see the source code for the `action plugins included with Ansible Core <https://
 Cache plugins
 -------------
 
-Cache plugins store gathered facts and data retrieved by inventory plugins.
+Cache plugins store gathered facts and data retrieved by inventory plugins. Only fact caching is currently supported by cache plugins in collections.
 
 Import cache plugins using the cache_loader so you can use ``self.set_options()`` and ``self.get_option(<option_name>)``. If you import a cache plugin directly in the code base, you can only access options via ``ansible.constants``, and you break the cache plugin's ability to be used by an inventory plugin.
 
@@ -246,7 +246,7 @@ but with an extra option so you can see how configuration works in Ansible versi
       """
       CALLBACK_VERSION = 2.0
       CALLBACK_TYPE = 'aggregate'
-      CALLBACK_NAME = 'timer'
+      CALLBACK_NAME = 'namespace.collection_name.timer'
 
       # only needed if you ship it and don't want to enable by default
       CALLBACK_NEEDS_WHITELIST = True
@@ -389,7 +389,7 @@ The following is an example of how this lookup is called::
   ---
   - hosts: all
     vars:
-       contents: "{{ lookup('file', '/etc/foo.txt') }}"
+       contents: "{{ lookup('namespace.collection_name.file', '/etc/foo.txt') }}"
 
     tasks:
 
@@ -418,7 +418,7 @@ Vars plugins
 
 Vars plugins inject additional variable data into Ansible runs that did not come from an inventory source, playbook, or command line. Playbook constructs like 'host_vars' and 'group_vars' work using vars plugins.
 
-Vars plugins were partially implemented in Ansible 2.0 and rewritten to be fully implemented starting with Ansible 2.4.
+Vars plugins were partially implemented in Ansible 2.0 and rewritten to be fully implemented starting with Ansible 2.4. Vars plugins are unsupported by collections.
 
 Older plugins used a ``run`` method as their main body/work:
 

docs/docsite/rst/plugins/cache.rst

@@ -34,6 +34,13 @@ or in the ``ansible.cfg`` file:
     [defaults]
     fact_caching=redis
 
+If the cache plugin is in a collection use the fully qualified name:
+
+.. code-block:: ini
+
+    [defaults]
+    fact_caching = namespace.collection_name.cache_plugin_name
+
 You will also need to configure other settings specific to each plugin. Consult the individual plugin documentation
 or the Ansible :ref:`configuration <ansible_configuration_settings>` for more details.
 
@@ -43,7 +50,7 @@ A custom cache plugin is enabled by dropping it into a ``cache_plugins`` directo
 Enabling Inventory Cache Plugins
 --------------------------------
 
-Inventory may be cached using a file-based cache plugin (like jsonfile). Check the specific inventory plugin to see if it supports caching.
+Inventory may be cached using a file-based cache plugin (like jsonfile). Check the specific inventory plugin to see if it supports caching. Cache plugins inside a collection are not supported for caching inventory.
 If an inventory-specific cache plugin is not specified Ansible will fall back to caching inventory with the fact cache plugin options.
 
 The inventory cache is disabled by default. You may enable it via environment variable:

docs/docsite/rst/plugins/callback.rst

@@ -34,7 +34,7 @@ Most callbacks shipped with Ansible are disabled by default and need to be white
 
 .. code-block:: ini
 
-  #callback_whitelist = timer, mail, profile_roles
+  #callback_whitelist = timer, mail, profile_roles, collection_namespace.collection_name.custom_callback
 
 Setting a callback plugin for ``ansible-playbook``
 --------------------------------------------------

docs/docsite/rst/plugins/inventory.rst

@@ -31,6 +31,15 @@ This list also establishes the order in which each plugin tries to parse an inve
    [inventory]
    enable_plugins = advanced_host_list, constructed, yaml
 
+The ``auto`` inventory plugin can be used to automatically determines which inventory plugin to use for a YAML configuration file. It can also be used for inventory plugins in a collection.
+
+To whitelist specific inventory plugins in a collection you need to use the fully qualified name:
+
+.. code-block:: ini
+
+   [inventory]
+   enable_plugins = namespace.collection_name.inventory_plugin_name
+
 
 .. _using_inventory:
 
@@ -55,6 +64,12 @@ Or for the openstack plugin the file has to be called ``clouds.yml`` or ``openst
     # clouds.yml or openstack.(yml|yaml)
     plugin: openstack
 
+To use a plugin in a collection provide the fully qualified name:
+
+.. code-block:: yaml
+
+    plugin: namespace.collection_name.inventory_plugin_name
+
 The ``auto`` inventory plugin is enabled by default and works by using the ``plugin`` field to indicate the plugin that should attempt to parse it. You can configure the whitelist/precedence of inventory plugins used to parse source using the `ansible.cfg` ['inventory'] ``enable_plugins`` list. After enabling the plugin and providing any required options, you can view the populated inventory with ``ansible-inventory -i demo.aws_ec2.yml --graph``:
 
 .. code-block:: text
@@ -65,6 +80,8 @@ The ``auto`` inventory plugin is enabled by default and works by using the ``plu
       |  |--ec2-98-765-432-10.compute-1.amazonaws.com
       |--@ungrouped:
 
+If you are using an inventory plugin in a playbook-adjacent collection and want to test your setup with ``ansible-inventory``, you will need to use the ``--playbook-dir`` flag.
+
 You can set the default inventory path (via ``inventory`` in the `ansible.cfg` [defaults] section or the :envvar:`ANSIBLE_INVENTORY` environment variable) to your inventory source(s). Now running ``ansible-inventory --graph`` should yield the same output as when you passed your YAML configuration source(s) directly. You can add custom inventory plugins to your plugin path to use in the same way.
 
 Your inventory source might be a directory of inventory configuration files. The constructed inventory plugin only operates on those hosts already in inventory, so you may want the constructed inventory configuration parsed at a particular point (such as last). Ansible parses the directory recursively, alphabetically. You cannot configure the parsing approach, so name your files to make it work predictably. Inventory plugins that extend constructed features directly can work around that restriction by adding constructed options in addition to the inventory plugin options. Otherwise, you can use ``-i`` with multiple sources to impose a specific order, e.g. ``-i demo.aws_ec2.yml -i clouds.yml -i constructed.yml``.
@@ -135,6 +152,8 @@ Here is an example of setting inventory caching with some fact caching defaults
    cache = yes
    cache_connection = /tmp/ansible_inventory
 
+Besides cache plugins shipped with Ansible, cache plugins eligible for caching inventory can also reside in a custom cache plugin path. Cache plugins in collections are not supported yet for inventory.
+
 .. _inventory_plugin_list:
 
 Plugin List