ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-06-28 11:10:21 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

fix YAML docs in multiple plugins (#10286)

Browse source 
* fix YAML docs in multiple plugins

* pfexec: fix short description

* adjust callback plugins

* fix wsl connection

* fix filter plugins

* fix inventory plugins

* minor adjustments in diy, print_task, xen_orchestra
This commit is contained in:
Alexei Znamensky 2025-06-24 16:23:46 +12:00 • committed by GitHub
parent 3ab7a898c6
commit e37cd1a015
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
25 changed files with 98 additions and 117 deletions
Download patch file Download diff file Expand all files Collapse all files

2
plugins/become/pfexec.py
View file

@ -6,7 +6,7 @@ from __future__ import annotations
DOCUMENTATION = r"""
name: pfexec
short_description: profile based execution
short_description: Profile based execution
description:
- This become plugins allows your remote/login user to execute commands as another user using the C(pfexec) utility.
author: Ansible Core Team

2
plugins/callback/context_demo.py
View file

@ -10,7 +10,7 @@ DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: context_demo
type: aggregate
short_description: demo callback that adds play/task context
short_description: Demo callback that adds play/task context
description:
- Displays some play and task context along with normal output.
- This is mostly for demo purposes.

2
plugins/callback/counter_enabled.py
View file

@ -12,7 +12,7 @@ DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: counter_enabled
type: stdout
short_description: adds counters to the output items (tasks and hosts/task)
short_description: Adds counters to the output items (tasks and hosts/task)
description:
- Use this callback when you need a kind of progress bar on a large environments.
- You will know how many tasks has the playbook to run, and which one is actually running.

2
plugins/callback/dense.py
View file

@ -9,7 +9,7 @@ from __future__ import annotations
DOCUMENTATION = r"""
name: dense
type: stdout
short_description: minimal stdout output
short_description: Minimal stdout output
extends_documentation_fragment:
- default_callback
description:

10
plugins/callback/diy.py
View file

@ -26,12 +26,12 @@ notes:
callback. Additionally, C(ansible_callback_diy.top_level_var_names) will output the top level variable names available
to the callback.
- Each option value is rendered as a template before being evaluated. This allows for the dynamic usage of an option. For
example, C("{{ 'yellow' if ansible_callback_diy.result.is_changed else 'bright green' }}").
- 'B(Condition) for all C(msg) options: if value C(is None or omit), then the option is not being used. B(Effect): use
of the C(default) callback plugin for output.'
- 'B(Condition) for all C(msg) options: if value C(is not None and not omit and length is not greater than 0), then the
example, V("{{ 'yellow' if ansible_callback_diy.result.is_changed else 'bright green' }}").
- 'B(Condition) for all C(msg) options: if value V(is None or omit), then the option is not being used. B(Effect): use of
the C(default) callback plugin for output.'
- 'B(Condition) for all C(msg) options: if value V(is not None and not omit and length is not greater than 0), then the
option is being used without output. B(Effect): suppress output.'
- 'B(Condition) for all C(msg) options: if value C(is not None and not omit and length is greater than 0), then the option
- 'B(Condition) for all C(msg) options: if value V(is not None and not omit and length is greater than 0), then the option
is being used with output. B(Effect): render value as template and output.'
- 'Valid color values: V(black), V(bright gray), V(blue), V(white), V(green), V(bright blue), V(cyan), V(bright green),
V(red), V(bright cyan), V(purple), V(bright red), V(yellow), V(bright purple), V(dark gray), V(bright yellow), V(magenta),

2
plugins/callback/jabber.py
View file

@ -10,7 +10,7 @@ DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: jabber
type: notification
short_description: post task events to a Jabber server
short_description: Post task events to a Jabber server
description:
- The chatty part of ChatOps with a Hipchat server as a target.
- This callback plugin sends status updates to a HipChat channel during playbook execution.

2
plugins/callback/log_plays.py
View file

@ -10,7 +10,7 @@ DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: log_plays
type: notification
short_description: write playbook output to log file
short_description: Write playbook output to log file
description:
- This callback writes playbook output to a file per host in the C(/var/log/ansible/hosts) directory.
requirements:

2
plugins/callback/null.py
View file

@ -12,7 +12,7 @@ name: 'null'
type: stdout
requirements:
- set as main display callback
short_description: do not display stuff to screen
short_description: Do not display stuff to screen
description:
- This callback prevents outputting events to screen.
"""

10
plugins/callback/print_task.py
View file

@ -6,7 +6,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
DOCUMENTATION = r"""
name: print_task
type: aggregate
short_description: Prints playbook task snippet to job output
@ -15,14 +15,14 @@ description:
version_added: 10.7.0
requirements:
- enable in configuration
'''
"""
EXAMPLES = r'''
ansible.cfg: >
EXAMPLES = r"""
ansible.cfg: |-
# Enable plugin
[defaults]
callbacks_enabled=community.general.print_task
'''
"""
from yaml import load, dump

2
plugins/callback/say.py
View file

@ -14,7 +14,7 @@ type: notification
requirements:
- whitelisting in configuration
- the C(/usr/bin/say) command line program (standard on macOS) or C(espeak) command line program
short_description: notify using software speech synthesizer
short_description: Notify using software speech synthesizer
description:
- This plugin will use the C(say) or C(espeak) program to "speak" about play events.
"""

2
plugins/callback/selective.py
View file

@ -12,7 +12,7 @@ name: selective
type: stdout
requirements:
- set as main display callback
short_description: only print certain tasks
short_description: Only print certain tasks
description:
- This callback only prints tasks that have been tagged with C(print_action) or that have failed. This allows operators
to focus on the tasks that provide value only.

2
plugins/callback/syslog_json.py
View file

@ -12,7 +12,7 @@ name: syslog_json
type: notification
requirements:
- whitelist in configuration
short_description: sends JSON events to syslog
short_description: Sends JSON events to syslog
description:
- This plugin logs ansible-playbook and ansible runs to a syslog server in JSON format.
options:

2
plugins/callback/unixy.py
View file

@ -11,7 +11,7 @@ DOCUMENTATION = r"""
name: unixy
type: stdout
author: Al Bowles (@akatch)
short_description: condensed Ansible output
short_description: Condensed Ansible output
description:
- Consolidated Ansible output in the style of LINUX/UNIX startup logs.
extends_documentation_fragment:

14
plugins/connection/wsl.py
View file

@ -128,7 +128,8 @@ options:
key: record_host_keys
type: boolean
host_key_checking:
description: "Set this to V(false) if you want to avoid host key checking by the underlying tools Ansible uses to connect to the host."
description: "Set this to V(false) if you want to avoid host key checking by the underlying tools Ansible uses to connect
to the host."
type: boolean
default: true
env:
@ -157,8 +158,7 @@ options:
type: float
default: 30
description:
- Configures, in seconds, the amount of time to wait for the SSH
banner to be presented.
- Configures, in seconds, the amount of time to wait for the SSH banner to be presented.
- This option is supported by paramiko version 1.15.0 or newer.
ini:
- section: paramiko_connection
@ -227,20 +227,20 @@ options:
- name: ansible_paramiko_user_known_hosts_file
wsl_distribution:
description:
- WSL distribution name
- WSL distribution name.
type: string
required: true
vars:
- name: wsl_distribution
wsl_user:
description:
- WSL distribution user
- WSL distribution user.
type: string
vars:
- name: wsl_user
become_user:
description:
- WSL distribution user
- WSL distribution user.
type: string
default: root
vars:
@ -248,7 +248,7 @@ options:
- name: ansible_become_user
become:
description:
- whether to use the user defined by ansible_become_user.
- Whether to use the user defined by O(become_user).
type: bool
default: false
vars:

11
plugins/filter/to_prettytable.py
View file

@ -30,17 +30,14 @@ options:
elements: string
column_alignments:
description:
- >-
Dictionary where keys are column names and values are alignment settings.
Valid alignment values are C(left), C(center), C(right), C(l), C(c), or C(r).
- >-
For example, V({'name': 'left', 'id': 'right'}) will align the C(name) column to the left
and the C(id) column to the right.
- Dictionary where keys are column names and values are alignment settings. Valid alignment values are C(left), C(center),
C(right), C(l), C(c), or C(r).
- "For example, V({'name': 'left', 'id': 'right'}) will align the C(name) column to the left and the C(id) column to
the right."
type: dictionary
"""
EXAMPLES = r"""
---
- name: Set a list of users
ansible.builtin.set_fact:
users:

8
plugins/inventory/cobbler.py
View file

@ -104,15 +104,15 @@ options:
default: true
want_ip_addresses:
description:
- Toggle, if V(true) the plugin will add a C(cobbler_ipv4_addresses) and C(cobbler_ipv6_addresses) dictionary to the defined O(group) mapping
interface DNS names to IP addresses.
- Toggle, if V(true) the plugin will add a C(cobbler_ipv4_addresses) and C(cobbler_ipv6_addresses) dictionary to the
defined O(group) mapping interface DNS names to IP addresses.
type: boolean
default: true
version_added: 7.1.0
facts_level:
description:
- "Set to V(normal) to gather only system-level variables."
- "Set to V(as_rendered) to gather all variables as rolled up by Cobbler."
- Set to V(normal) to gather only system-level variables.
- Set to V(as_rendered) to gather all variables as rolled up by Cobbler.
type: string
choices: ['normal', 'as_rendered']
default: normal

6
plugins/inventory/gitlab_runners.py
View file

@ -11,7 +11,7 @@ DOCUMENTATION = r"""
name: gitlab_runners
author:
- Stefan Heitmüller (@morph027) <stefan.heitmueller@gmx.com>
short_description: Ansible dynamic inventory plugin for GitLab runners.
short_description: Ansible dynamic inventory plugin for GitLab runners
requirements:
- python-gitlab > 1.8.0
extends_documentation_fragment:
@ -44,14 +44,14 @@ options:
- private_token
- access_token
filter:
description: filter runners from GitLab API
description: Filter runners from GitLab API.
env:
- name: GITLAB_FILTER
version_added: 1.0.0
type: str
choices: ['active', 'paused', 'online', 'specific', 'shared']
verbose_output:
description: Toggle to (not) include all available nodes metadata
description: Toggle to (not) include all available nodes metadata.
type: bool
default: true
"""

5
plugins/inventory/icinga2.py
View file

@ -14,8 +14,7 @@ author:
- Cliff Hults (@BongoEADGC6) <cliff.hults@gmail.com>
description:
- Get inventory hosts from the Icinga2 API.
- "Uses a configuration file as an inventory source, it must end in
C(.icinga2.yml) or C(.icinga2.yaml)."
- Uses a configuration file as an inventory source, it must end in C(.icinga2.yml) or C(.icinga2.yaml).
extends_documentation_fragment:
- constructed
options:
@ -46,7 +45,7 @@ options:
required: true
host_filter:
description:
- An Icinga2 API valid host filter. Leave blank for no filtering
- An Icinga2 API valid host filter. Leave blank for no filtering.
type: string
required: false
validate_certs:

48
plugins/inventory/iocage.py
View file

@ -8,29 +8,25 @@ from __future__ import annotations
DOCUMENTATION = r"""
name: iocage
short_description: iocage inventory source
short_description: C(iocage) inventory source
version_added: 10.2.0
author:
- Vladimir Botka (@vbotka)
requirements:
- iocage >= 1.8
description:
- Get inventory hosts from the iocage jail manager running on O(host).
- By default, O(host) is V(localhost). If O(host) is not V(localhost) it
is expected that the user running Ansible on the controller can
connect to the O(host) account O(user) with SSH non-interactively and
execute the command C(iocage list).
- Uses a configuration file as an inventory source, it must end
in C(.iocage.yml) or C(.iocage.yaml).
- Get inventory hosts from the C(iocage) jail manager running on O(host).
- By default, O(host) is V(localhost). If O(host) is not V(localhost) it is expected that the user running Ansible on the
controller can connect to the O(host) account O(user) with SSH non-interactively and execute the command C(iocage list).
- Uses a configuration file as an inventory source, it must end in C(.iocage.yml) or C(.iocage.yaml).
extends_documentation_fragment:
- ansible.builtin.constructed
- ansible.builtin.inventory_cache
options:
plugin:
description:
- The name of this plugin, it should always be set to
V(community.general.iocage) for this plugin to recognize
it as its own.
- The name of this plugin, it should always be set to V(community.general.iocage) for this plugin to recognize it as
its own.
required: true
choices: ['community.general.iocage']
type: str
@ -40,10 +36,8 @@ options:
default: localhost
user:
description:
- C(iocage) user.
It is expected that the O(user) is able to connect to the
O(host) with SSH and execute the command C(iocage list).
This option is not required if O(host) is V(localhost).
- C(iocage) user. It is expected that the O(user) is able to connect to the O(host) with SSH and execute the command
C(iocage list). This option is not required if O(host=localhost).
type: str
sudo:
description:
@ -61,8 +55,7 @@ options:
version_added: 10.3.0
get_properties:
description:
- Get jails' properties.
Creates dictionary C(iocage_properties) for each added host.
- Get jails' properties. Creates dictionary C(iocage_properties) for each added host.
type: bool
default: false
env:
@ -84,7 +77,7 @@ options:
description:
- The name of the tag in the C(iocage properties notes) that contains the jails alias.
- By default, the C(iocage list -l) column C(NAME) is used to name the jail.
- This option requires the notes format C("t1=v1 t2=v2 ...")
- This option requires the notes format C("t1=v1 t2=v2 ...").
- The option O(get_properties) must be enabled.
type: str
version_added: 11.0.0
@ -95,21 +88,16 @@ options:
default: false
version_added: 11.0.0
notes:
- You might want to test the command C(ssh user@host iocage list -l) on
the controller before using this inventory plugin with O(user) specified
and with O(host) other than V(localhost).
- If you run this inventory plugin on V(localhost) C(ssh) is not used.
In this case, test the command C(iocage list -l).
- You might want to test the command C(ssh user@host iocage list -l) on the controller before using this inventory plugin
with O(user) specified and with O(host) other than V(localhost).
- If you run this inventory plugin on V(localhost) C(ssh) is not used. In this case, test the command C(iocage list -l).
- This inventory plugin creates variables C(iocage_*) for each added host.
- The values of these variables are collected from the output of the
command C(iocage list -l).
- The values of these variables are collected from the output of the command C(iocage list -l).
- The names of these variables correspond to the output columns.
- The column C(NAME) is used to name the added host.
- The option O(hooks_results) expects the C(poolname) of a jail is mounted to
C(/poolname). For example, if you activate the pool C(iocage) this plugin
expects to find the O(hooks_results) items in the path
C(/iocage/iocage/jails/<name>/root). If you mount the C(poolname) to a
different path the easiest remedy is to create a symlink.
- The option O(hooks_results) expects the C(poolname) of a jail is mounted to C(/poolname). For example, if you activate
the pool C(iocage) this plugin expects to find the O(hooks_results) items in the path C(/iocage/iocage/jails/<name>/root).
If you mount the C(poolname) to a different path the easiest remedy is to create a symlink.
"""
EXAMPLES = r"""

5
plugins/inventory/linode.py
View file

@ -9,15 +9,14 @@ DOCUMENTATION = r"""
name: linode
author:
- Luke Murphy (@decentral1se)
short_description: Ansible dynamic inventory plugin for Linode.
short_description: Ansible dynamic inventory plugin for Linode
requirements:
- linode_api4 >= 2.0.0
description:
- Reads inventories from the Linode API v4.
- Uses a YAML configuration file that ends with linode.(yml|yaml).
- Linode labels are used by default as the hostnames.
- The default inventory groups are built from groups (deprecated by
Linode) and not tags.
- The default inventory groups are built from groups (deprecated by Linode) and not tags.
extends_documentation_fragment:
- constructed
- inventory_cache

12
plugins/inventory/nmap.py
View file

@ -18,7 +18,7 @@ requirements:
- nmap CLI installed
options:
plugin:
description: token that ensures this is a source file for the 'nmap' plugin.
description: Token that ensures this is a source file for the P(community.general.nmap#inventory) plugin.
type: string
required: true
choices: ['nmap', 'community.general.nmap']
@ -46,8 +46,8 @@ options:
port:
description:
- Only scan specific port or port range (C(-p)).
- For example, you could pass V(22) for a single port, V(1-65535) for a range of ports,
or V(U:53,137,T:21-25,139,8080,S:9) to check port 53 with UDP, ports 21-25 with TCP, port 9 with SCTP, and ports 137, 139, and 8080 with all.
- For example, you could pass V(22) for a single port, V(1-65535) for a range of ports, or V(U:53,137,T:21-25,139,8080,S:9)
to check port 53 with UDP, ports 21-25 with TCP, port 9 with SCTP, and ports 137, 139, and 8080 with all.
type: string
version_added: 6.5.0
ports:
@ -55,11 +55,11 @@ options:
type: boolean
default: true
ipv4:
description: use IPv4 type addresses
description: Use IPv4 type addresses.
type: boolean
default: true
ipv6:
description: use IPv6 type addresses
description: Use IPv6 type addresses.
type: boolean
default: true
udp_scan:
@ -98,7 +98,7 @@ options:
version_added: 7.4.0
notes:
- At least one of O(ipv4) or O(ipv6) is required to be V(true); both can be V(true), but they cannot both be V(false).
- 'TODO: add OS fingerprinting'
- 'TODO: add OS fingerprinting.'
"""
EXAMPLES = r"""
---

2
plugins/inventory/online.py
View file

@ -14,7 +14,7 @@ description:
- Get inventory hosts from Scaleway (previously Online SAS or Online.net).
options:
plugin:
description: token that ensures this is a source file for the 'online' plugin.
description: Token that ensures this is a source file for the P(community.general.online#inventory) plugin.
type: string
required: true
choices: ['online', 'community.general.online']

16
plugins/inventory/opennebula.py
View file

@ -16,8 +16,7 @@ extends_documentation_fragment:
- constructed
description:
- Get inventory hosts from OpenNebula cloud.
- Uses an YAML configuration file ending with either C(opennebula.yml) or C(opennebula.yaml)
to set parameter values.
- Uses an YAML configuration file ending with either C(opennebula.yml) or C(opennebula.yaml) to set parameter values.
- Uses O(api_authfile), C(~/.one/one_auth), or E(ONE_AUTH) pointing to a OpenNebula credentials file.
options:
plugin:
@ -28,8 +27,7 @@ options:
api_url:
description:
- URL of the OpenNebula RPC server.
- It is recommended to use HTTPS so that the username/password are not
transferred over the network unencrypted.
- It is recommended to use HTTPS so that the username/password are not transferred over the network unencrypted.
- If not set then the value of the E(ONE_URL) environment variable is used.
env:
- name: ONE_URL
@ -37,8 +35,8 @@ options:
type: string
api_username:
description:
- Name of the user to login into the OpenNebula RPC server. If not set
then the value of the E(ONE_USERNAME) environment variable is used.
- Name of the user to login into the OpenNebula RPC server. If not set then the value of the E(ONE_USERNAME) environment
variable is used.
env:
- name: ONE_USERNAME
type: string
@ -52,8 +50,8 @@ options:
type: string
api_authfile:
description:
- If both O(api_username) or O(api_password) are not set, then it will try
authenticate with ONE auth file. Default path is C(~/.one/one_auth).
- If both O(api_username) or O(api_password) are not set, then it will try authenticate with ONE auth file. Default
path is C(~/.one/one_auth).
- Set environment variable E(ONE_AUTH) to override this path.
env:
- name: ONE_AUTH
@ -71,7 +69,7 @@ options:
description: Only return servers filtered by this label.
type: string
group_by_labels:
description: Create host groups by vm labels
description: Create host groups by VM labels.
type: bool
default: true
"""

9
plugins/inventory/scaleway.py
View file

@ -37,7 +37,8 @@ options:
scw_profile:
description:
- The config profile to use in config file.
- By default uses the one specified as C(active_profile) in the config file, or falls back to V(default) if that is not defined.
- By default uses the one specified as C(active_profile) in the config file, or falls back to V(default) if that is
not defined.
type: string
version_added: 4.4.0
oauth_token:
@ -65,10 +66,8 @@ options:
- hostname
- id
variables:
description: 'Set individual variables: keys are variable names and
values are templates. Any value returned by the
L(Scaleway API, https://developer.scaleway.com/#servers-server-get)
can be used.'
description: 'Set individual variables: keys are variable names and values are templates. Any value returned by the L(Scaleway
API, https://developer.scaleway.com/#servers-server-get) can be used.'
type: dict
"""

31
plugins/inventory/virtualbox.py
View file

@ -8,47 +8,48 @@ from __future__ import annotations
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: virtualbox
short_description: virtualbox inventory source
short_description: Virtualbox inventory source
description:
- Get inventory hosts from the local virtualbox installation.
- Uses a YAML configuration file that ends with virtualbox.(yml|yaml) or vbox.(yml|yaml).
- The inventory_hostname is always the 'Name' of the virtualbox instance.
- Groups can be assigned to the VMs using C(VBoxManage). Multiple groups can be assigned by using V(/) as a delimeter.
- A separate parameter, O(enable_advanced_group_parsing) is exposed to change grouping behaviour. See the parameter documentation for details.
- A separate parameter, O(enable_advanced_group_parsing) is exposed to change grouping behaviour. See the parameter documentation
for details.
extends_documentation_fragment:
- constructed
- inventory_cache
options:
plugin:
description: token that ensures this is a source file for the 'virtualbox' plugin
description: Token that ensures this is a source file for the P(community.general.virtualbox#inventory) plugin.
type: string
required: true
choices: ['virtualbox', 'community.general.virtualbox']
running_only:
description: toggles showing all vms vs only those currently running
description: Toggles showing all VMs instead of only those currently running.
type: boolean
default: false
settings_password_file:
description: provide a file containing the settings password (equivalent to --settingspwfile)
description: Provide a file containing the settings password (equivalent to C(--settingspwfile)).
type: string
network_info_path:
description: property path to query for network information (ansible_host)
description: Property path to query for network information (C(ansible_host)).
type: string
default: "/VirtualBox/GuestInfo/Net/0/V4/IP"
query:
description: create vars from virtualbox properties
description: Create vars from virtualbox properties.
type: dictionary
default: {}
enable_advanced_group_parsing:
description:
- The default group parsing rule (when this setting is set to V(false)) is to split the VirtualBox VM's group based on the V(/) character and
assign the resulting list elements as an Ansible Group.
- Setting O(enable_advanced_group_parsing=true) changes this behaviour to match VirtualBox's interpretation of groups according to
U(https://www.virtualbox.org/manual/UserManual.html#gui-vmgroups).
Groups are now split using the V(,) character, and the V(/) character indicates nested groups.
- When enabled, a VM that's been configured using V(VBoxManage modifyvm "vm01" --groups "/TestGroup/TestGroup2,/TestGroup3") will result in
the group C(TestGroup2) being a child group of C(TestGroup); and
the VM being a part of C(TestGroup2) and C(TestGroup3).
- The default group parsing rule (when this setting is set to V(false)) is to split the VirtualBox VM's group based
on the V(/) character and assign the resulting list elements as an Ansible Group.
- Setting O(enable_advanced_group_parsing=true) changes this behaviour to match VirtualBox's interpretation of groups
according to U(https://www.virtualbox.org/manual/UserManual.html#gui-vmgroups). Groups are now split using the V(,)
character, and the V(/) character indicates nested groups.
- When enabled, a VM that's been configured using V(VBoxManage modifyvm "vm01" --groups "/TestGroup/TestGroup2,/TestGroup3")
will result in the group C(TestGroup2) being a child group of C(TestGroup); and the VM being a part of C(TestGroup2)
and C(TestGroup3).
default: false
type: bool
version_added: 9.2.0