add details on some plugin options - AI-assisted (#2813) (#2900)

* add details on some plugin options

* revise based on feedback

* Apply suggestions from code review



* Update docs/docsite/rst/dev_guide/developing_plugins.rst

* Apply suggestions from code review



* add examples

* Update docs/docsite/rst/dev_guide/developing_plugins.rst



* Apply suggestions from code review



---------




(cherry picked from commit caa2399)

Co-authored-by: Sandra McCann <[email protected]>
Co-authored-by: Felix Fontein <[email protected]>
Co-authored-by: Don Naro <[email protected]>
Co-authored-by: Andrew Klychkov <[email protected]>

Author: 5 people

docs/docsite/rst/dev_guide/developing_plugins.rst

@@ -63,18 +63,67 @@ To define configurable options for your plugin, describe them in the ``DOCUMENTA
         description: describe this config option
         default: default value for this config option
         env:
-          - name: NAME_OF_ENV_VAR
+          - name: MYCOLLECTION_NAME_ENV_VAR_NAME
         ini:
-          - section: section_of_ansible.cfg_where_this_config_option_is_defined
+          - section: mycollection_section_of_ansible.cfg_where_this_config_option_is_defined
             key: key_used_in_ansible.cfg
         vars:
-          - name: name_of_ansible_var
-          - name: name_of_second_var
+          - name: mycollection_name_of_ansible_var
+          - name: mycollection_name_of_second_var
             version_added: X.x
         required: True/False
         type: boolean/float/integer/list/none/path/pathlist/pathspec/string/tmppath
         version_added: X.x
 
+The supported configuration fields are:
+
+**env**
+  List of environment variables that can be used to set this option.
+  Each entry includes a ``name`` field specifying the environment variable name.
+  The name should be in uppercase and should be prefixed with the collection name.
+  Multiple environment variables can be listed for the same option.
+  The last set environment variable in the list takes precedence if multiple are set.
+  This is commonly used for plugins (especially inventory plugins) to allow configuration through environment variables.
+  Examples: ``VMWARE_PORT``, ``GRAFANA_PASSWORD``
+  
+
+**ini**
+  List of configuration file settings that can be used to set this option.
+  Each entry includes a ``section`` field for the configuration file section and a ``key`` field for the configuration key. Both should be in lowercase and should be prefixed with the collection name.
+  Multiple configuration settings can be listed for the same option.
+  The last set configuration setting in the list takes precedence if multiple are set.
+  This allows plugins to be configured with ansible.cfg.
+  Example: ``grafana_password``
+  
+
+**vars**
+  List of Ansible variables that can be used to set this option.
+  Each entry includes a ``name`` field specifying the variable name.
+  The name should be in lowercase and should be prefixed with the collection name.
+  Multiple variables can be listed for the same option.
+  The last set variable in the list takes precedence if multiple are set.
+  Variables follow Ansible's variable precedence rules.
+  This allows plugins to be configured with Ansible variables.
+  Example: ``ansible_vmware_port``
+
+.. _general_plugin_precedence_rules:
+
+General precedence rules
+------------------------
+
+ The precedence rules for configuration sources are listed below, starting with the highest precedence values:
+
+* Keywords
+* CLI settings
+* Environment variables (``env``)
+* Values defined in ``ansible.cfg``
+* Default value for the option, if present.
+
+.. _accessing_configuration_settings:
+
+Accessing configuration settings
+--------------------------------
+
 To access the configuration settings in your plugin, use ``self.get_option(<option_name>)``. 
 Some plugin types handle this differently: