diff options
| author | Brian Scholer <1260690+briantist@users.noreply.github.com> | 2021-09-24 13:50:32 -0400 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-09-24 10:50:32 -0700 |
| commit | f4cdea96451b9e028a6559fa184952d037edf929 (patch) | |
| tree | 70f959b1526cafea3cb44c5820324e924cbe2eb5 | |
| parent | 5183a2e58523c95768071c70e15b8d5fb1a29818 (diff) | |
| download | ansible-f4cdea96451b9e028a6559fa184952d037edf929.tar.gz | |
docs - add some info on plugin option source precedence (#75754)
* docs - add some info on plugin option source precedence
##### SUMMARY
Add some clarity on precedence, especially from sources of the same type.
##### ISSUE TYPE
- Docs Pull Request
+label: docsite_pr
* update RST formatting
* Update docs/docsite/rst/dev_guide/developing_plugins.rst
Apply review suggestions
Co-authored-by: Aine Riordan <44700011+ariordan-redhat@users.noreply.github.com>
Co-authored-by: Aine Riordan <44700011+ariordan-redhat@users.noreply.github.com>
| -rw-r--r-- | docs/docsite/rst/dev_guide/developing_plugins.rst | 6 |
1 files changed, 6 insertions, 0 deletions
diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index d14aaeb654..a18fe77ceb 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -67,12 +67,18 @@ To define configurable options for your plugin, describe them in the ``DOCUMENTA ini: - section: 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 + version_added: X.x required: True/False type: boolean/float/integer/list/none/path/pathlist/pathspec/string/tmppath version_added: X.x To access the configuration settings in your plugin, use ``self.get_option(<option_name>)``. For the plugin types (such as 'become', 'cache', 'callback', 'cliconf', 'connection', 'httpapi', 'inventory', 'lookup', 'netconf', 'shell', and 'vars') that support embedded documentation, the controller pre-populates the settings. If you need to populate settings explicitly, use a ``self.set_options()`` call. +Configuration sources follow the precedence rules for values in Ansible. When there are multiple values from the same category, the value defined last takes precedence. For example, in the above configuration block, if both ``name_of_ansible_var`` and ``name_of_second_var`` are defined, the value of the ``option_name`` option will be the value of ``name_of_second_var``. Refer to :ref:`general_precedence_rules` for further information. + Plugins that support embedded documentation (see :ref:`ansible-doc` for the list) should include well-formed doc strings. If you inherit from a plugin, you must document the options it takes, either via a documentation fragment or as a copy. See :ref:`module_documenting` for more information on correct documentation. Thorough documentation is a good idea even if you're developing a plugin for local use. Developing particular plugin types |