From e37cd1a0151ec89f29472dd68750d8e90a031ee7 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Tue, 24 Jun 2025 16:23:46 +1200 Subject: [PATCH] fix YAML docs in multiple plugins (#10286) * 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 --- plugins/become/pfexec.py | 2 +- plugins/callback/context_demo.py | 2 +- plugins/callback/counter_enabled.py | 2 +- plugins/callback/dense.py | 2 +- plugins/callback/diy.py | 10 +++--- plugins/callback/jabber.py | 2 +- plugins/callback/log_plays.py | 2 +- plugins/callback/null.py | 2 +- plugins/callback/print_task.py | 16 +++++----- plugins/callback/say.py | 2 +- plugins/callback/selective.py | 2 +- plugins/callback/syslog_json.py | 2 +- plugins/callback/unixy.py | 2 +- plugins/connection/wsl.py | 14 ++++----- plugins/filter/to_prettytable.py | 11 +++---- plugins/inventory/cobbler.py | 8 ++--- plugins/inventory/gitlab_runners.py | 6 ++-- plugins/inventory/icinga2.py | 5 ++- plugins/inventory/iocage.py | 48 +++++++++++------------------ plugins/inventory/linode.py | 5 ++- plugins/inventory/nmap.py | 12 ++++---- plugins/inventory/online.py | 2 +- plugins/inventory/opennebula.py | 16 +++++----- plugins/inventory/scaleway.py | 9 +++--- plugins/inventory/virtualbox.py | 31 ++++++++++--------- 25 files changed, 98 insertions(+), 117 deletions(-) diff --git a/plugins/become/pfexec.py b/plugins/become/pfexec.py index 65690f359b..9faf1ffc63 100644 --- a/plugins/become/pfexec.py +++ b/plugins/become/pfexec.py @@ -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 diff --git a/plugins/callback/context_demo.py b/plugins/callback/context_demo.py index 28be2882b6..e846aa2786 100644 --- a/plugins/callback/context_demo.py +++ b/plugins/callback/context_demo.py @@ -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. diff --git a/plugins/callback/counter_enabled.py b/plugins/callback/counter_enabled.py index 15fc85a01b..833a864ef3 100644 --- a/plugins/callback/counter_enabled.py +++ b/plugins/callback/counter_enabled.py @@ -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. diff --git a/plugins/callback/dense.py b/plugins/callback/dense.py index 052bd4ea6f..cc8952e774 100644 --- a/plugins/callback/dense.py +++ b/plugins/callback/dense.py @@ -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: diff --git a/plugins/callback/diy.py b/plugins/callback/diy.py index a4369daadd..40f3347b49 100644 --- a/plugins/callback/diy.py +++ b/plugins/callback/diy.py @@ -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), diff --git a/plugins/callback/jabber.py b/plugins/callback/jabber.py index 10aa866142..29838ef4fd 100644 --- a/plugins/callback/jabber.py +++ b/plugins/callback/jabber.py @@ -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. diff --git a/plugins/callback/log_plays.py b/plugins/callback/log_plays.py index 483976acae..b89d1b03af 100644 --- a/plugins/callback/log_plays.py +++ b/plugins/callback/log_plays.py @@ -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: diff --git a/plugins/callback/null.py b/plugins/callback/null.py index b59389e39a..0527c1c467 100644 --- a/plugins/callback/null.py +++ b/plugins/callback/null.py @@ -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. """ diff --git a/plugins/callback/print_task.py b/plugins/callback/print_task.py index 7407b0e803..809baddb95 100644 --- a/plugins/callback/print_task.py +++ b/plugins/callback/print_task.py @@ -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: > - # Enable plugin - [defaults] - callbacks_enabled=community.general.print_task -''' +EXAMPLES = r""" +ansible.cfg: |- + # Enable plugin + [defaults] + callbacks_enabled=community.general.print_task +""" from yaml import load, dump diff --git a/plugins/callback/say.py b/plugins/callback/say.py index e6da490ec7..a5b82cb148 100644 --- a/plugins/callback/say.py +++ b/plugins/callback/say.py @@ -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. """ diff --git a/plugins/callback/selective.py b/plugins/callback/selective.py index 9cc805d3cd..53d40671bc 100644 --- a/plugins/callback/selective.py +++ b/plugins/callback/selective.py @@ -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. diff --git a/plugins/callback/syslog_json.py b/plugins/callback/syslog_json.py index 9e5c78c90c..e4b50bbc32 100644 --- a/plugins/callback/syslog_json.py +++ b/plugins/callback/syslog_json.py @@ -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: diff --git a/plugins/callback/unixy.py b/plugins/callback/unixy.py index 48f9b2d1f0..8fd8c10c94 100644 --- a/plugins/callback/unixy.py +++ b/plugins/callback/unixy.py @@ -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: diff --git a/plugins/connection/wsl.py b/plugins/connection/wsl.py index 6f2fec5102..24e47ecae5 100644 --- a/plugins/connection/wsl.py +++ b/plugins/connection/wsl.py @@ -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: diff --git a/plugins/filter/to_prettytable.py b/plugins/filter/to_prettytable.py index 249c830230..34da0481d4 100644 --- a/plugins/filter/to_prettytable.py +++ b/plugins/filter/to_prettytable.py @@ -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: diff --git a/plugins/inventory/cobbler.py b/plugins/inventory/cobbler.py index 3526093b8c..4646a07b2a 100644 --- a/plugins/inventory/cobbler.py +++ b/plugins/inventory/cobbler.py @@ -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 diff --git a/plugins/inventory/gitlab_runners.py b/plugins/inventory/gitlab_runners.py index 192be319a7..5b7f4c504c 100644 --- a/plugins/inventory/gitlab_runners.py +++ b/plugins/inventory/gitlab_runners.py @@ -11,7 +11,7 @@ DOCUMENTATION = r""" name: gitlab_runners author: - Stefan Heitmüller (@morph027) -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 """ diff --git a/plugins/inventory/icinga2.py b/plugins/inventory/icinga2.py index 5b549d8e9c..64d77b437d 100644 --- a/plugins/inventory/icinga2.py +++ b/plugins/inventory/icinga2.py @@ -14,8 +14,7 @@ author: - Cliff Hults (@BongoEADGC6) 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: diff --git a/plugins/inventory/iocage.py b/plugins/inventory/iocage.py index 15621aa2dd..603003d617 100644 --- a/plugins/inventory/iocage.py +++ b/plugins/inventory/iocage.py @@ -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//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//root). + If you mount the C(poolname) to a different path the easiest remedy is to create a symlink. """ EXAMPLES = r""" diff --git a/plugins/inventory/linode.py b/plugins/inventory/linode.py index 53d86f21d3..bf6faba07a 100644 --- a/plugins/inventory/linode.py +++ b/plugins/inventory/linode.py @@ -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 diff --git a/plugins/inventory/nmap.py b/plugins/inventory/nmap.py index f8a792964c..502fbf2840 100644 --- a/plugins/inventory/nmap.py +++ b/plugins/inventory/nmap.py @@ -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""" --- diff --git a/plugins/inventory/online.py b/plugins/inventory/online.py index e88deb4012..8b4821a009 100644 --- a/plugins/inventory/online.py +++ b/plugins/inventory/online.py @@ -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'] diff --git a/plugins/inventory/opennebula.py b/plugins/inventory/opennebula.py index 7bf6ccf224..b547d595eb 100644 --- a/plugins/inventory/opennebula.py +++ b/plugins/inventory/opennebula.py @@ -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 """ diff --git a/plugins/inventory/scaleway.py b/plugins/inventory/scaleway.py index 488bbbe084..c258008e41 100644 --- a/plugins/inventory/scaleway.py +++ b/plugins/inventory/scaleway.py @@ -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 """ diff --git a/plugins/inventory/virtualbox.py b/plugins/inventory/virtualbox.py index d94cd64110..dc28e76cc4 100644 --- a/plugins/inventory/virtualbox.py +++ b/plugins/inventory/virtualbox.py @@ -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