From 9fc3092bb3e8cd7f96dce273b9f19b0efa51bd49 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Thu, 26 Dec 2024 20:22:58 +1300 Subject: [PATCH] s[e-n]*: normalize docs (#9352) * s[e-n]*: normalize docs * Apply suggestions from code review Co-authored-by: Felix Fontein * quote line with : and remove extraneous notes * Update plugins/modules/slack.py Co-authored-by: Felix Fontein * Update plugins/modules/seport.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein --- plugins/modules/sefcontext.py | 94 ++++++------ plugins/modules/selinux_permissive.py | 27 ++-- plugins/modules/selogin.py | 37 +++-- plugins/modules/sendgrid.py | 38 ++--- plugins/modules/sensu_check.py | 65 ++++---- plugins/modules/sensu_client.py | 26 ++-- plugins/modules/sensu_handler.py | 33 ++--- plugins/modules/sensu_silence.py | 30 ++-- plugins/modules/sensu_subscription.py | 35 +++-- plugins/modules/seport.py | 31 ++-- plugins/modules/serverless.py | 26 ++-- plugins/modules/shutdown.py | 33 +++-- plugins/modules/simpleinit_msb.py | 20 +-- plugins/modules/sl_vm.py | 163 ++++++++++---------- plugins/modules/slack.py | 83 +++++------ plugins/modules/slackpkg.py | 64 ++++---- plugins/modules/smartos_image_info.py | 43 +++--- plugins/modules/snap.py | 193 ++++++++++++------------ plugins/modules/snap_alias.py | 71 +++++---- plugins/modules/snmp_facts.py | 204 +++++++++++++------------- 20 files changed, 627 insertions(+), 689 deletions(-) diff --git a/plugins/modules/sefcontext.py b/plugins/modules/sefcontext.py index 19c128fa7b..eeba491f5d 100644 --- a/plugins/modules/sefcontext.py +++ b/plugins/modules/sefcontext.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: sefcontext short_description: Manages SELinux file context mapping definitions description: @@ -28,85 +27,82 @@ attributes: options: target: description: - - Target path (expression). + - Target path (expression). type: str required: true - aliases: [ path ] + aliases: [path] ftype: description: - - The file type that should have SELinux contexts applied. - - "The following file type options are available:" - - V(a) for all files, - - V(b) for block devices, - - V(c) for character devices, - - V(d) for directories, - - V(f) for regular files, - - V(l) for symbolic links, - - V(p) for named pipes, - - V(s) for socket files. + - The file type that should have SELinux contexts applied. + - 'The following file type options are available:' + - V(a) for all files, + - V(b) for block devices, + - V(c) for character devices, + - V(d) for directories, + - V(f) for regular files, + - V(l) for symbolic links, + - V(p) for named pipes, + - V(s) for socket files. type: str - choices: [ a, b, c, d, f, l, p, s ] + choices: [a, b, c, d, f, l, p, s] default: a setype: description: - - SELinux type for the specified O(target). + - SELinux type for the specified O(target). type: str substitute: description: - - Path to use to substitute file context(s) for the specified O(target). The context labeling for the O(target) subtree is made equivalent to this path. - - This is also referred to as SELinux file context equivalence and it implements the C(equal) functionality of the SELinux management tools. + - Path to use to substitute file context(s) for the specified O(target). The context labeling for the O(target) subtree is made equivalent + to this path. + - This is also referred to as SELinux file context equivalence and it implements the C(equal) functionality of the SELinux management tools. version_added: 6.4.0 type: str - aliases: [ equal ] + aliases: [equal] seuser: description: - - SELinux user for the specified O(target). - - Defaults to V(system_u) for new file contexts and to existing value when modifying file contexts. + - SELinux user for the specified O(target). + - Defaults to V(system_u) for new file contexts and to existing value when modifying file contexts. type: str selevel: description: - - SELinux range for the specified O(target). - - Defaults to V(s0) for new file contexts and to existing value when modifying file contexts. + - SELinux range for the specified O(target). + - Defaults to V(s0) for new file contexts and to existing value when modifying file contexts. type: str - aliases: [ serange ] + aliases: [serange] state: description: - - Whether the SELinux file context must be V(absent) or V(present). - - Specifying V(absent) without either O(setype) or O(substitute) deletes both SELinux type or path substitution mappings that match O(target). + - Whether the SELinux file context must be V(absent) or V(present). + - Specifying V(absent) without either O(setype) or O(substitute) deletes both SELinux type or path substitution mappings that match O(target). type: str - choices: [ absent, present ] + choices: [absent, present] default: present reload: description: - - Reload SELinux policy after commit. - - Note that this does not apply SELinux file contexts to existing files. + - Reload SELinux policy after commit. + - Note that this does not apply SELinux file contexts to existing files. type: bool default: true ignore_selinux_state: description: - - Useful for scenarios (chrooted environment) that you can't get the real SELinux state. + - Useful for scenarios (chrooted environment) that you cannot get the real SELinux state. type: bool default: false notes: -- The changes are persistent across reboots. -- O(setype) and O(substitute) are mutually exclusive. -- If O(state=present) then one of O(setype) or O(substitute) is mandatory. -- The M(community.general.sefcontext) module does not modify existing files to the new - SELinux context(s), so it is advisable to first create the SELinux - file contexts before creating files, or run C(restorecon) manually - for the existing files that require the new SELinux file contexts. -- Not applying SELinux fcontexts to existing files is a deliberate - decision as it would be unclear what reported changes would entail - to, and there's no guarantee that applying SELinux fcontext does - not pick up other unrelated prior changes. + - The changes are persistent across reboots. + - O(setype) and O(substitute) are mutually exclusive. + - If O(state=present) then one of O(setype) or O(substitute) is mandatory. + - The M(community.general.sefcontext) module does not modify existing files to the new SELinux context(s), so it is advisable to first create + the SELinux file contexts before creating files, or run C(restorecon) manually for the existing files that require the new SELinux file contexts. + - Not applying SELinux fcontexts to existing files is a deliberate decision as it would be unclear what reported changes would entail to, and + there is no guarantee that applying SELinux fcontext does not pick up other unrelated prior changes. requirements: -- libselinux-python -- policycoreutils-python + - libselinux-python + - policycoreutils-python author: -- Dag Wieers (@dagwieers) -''' + - Dag Wieers (@dagwieers) +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Allow apache to modify files in /srv/git_repos community.general.sefcontext: target: '/srv/git_repos(/.*)?' @@ -132,11 +128,11 @@ EXAMPLES = r''' - name: Apply new SELinux file context to filesystem ansible.builtin.command: restorecon -irv /srv/git_repos -''' +""" -RETURN = r''' +RETURN = r""" # Default return values -''' +""" import traceback diff --git a/plugins/modules/selinux_permissive.py b/plugins/modules/selinux_permissive.py index 80439e1de7..b5c0ee4a61 100644 --- a/plugins/modules/selinux_permissive.py +++ b/plugins/modules/selinux_permissive.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: selinux_permissive short_description: Change permissive domain in SELinux policy description: @@ -25,20 +24,20 @@ attributes: options: domain: description: - - The domain that will be added or removed from the list of permissive domains. + - The domain that will be added or removed from the list of permissive domains. type: str required: true - aliases: [ name ] + aliases: [name] permissive: description: - - Indicate if the domain should or should not be set as permissive. + - Indicate if the domain should or should not be set as permissive. type: bool required: true no_reload: description: - - Disable reloading of the SELinux policy after making change to a domain's permissive setting. - - The default is V(false), which causes policy to be reloaded when a domain changes state. - - Reloading the policy does not work on older versions of the C(policycoreutils-python) library, for example in EL 6." + - Disable reloading of the SELinux policy after making change to a domain's permissive setting. + - The default is V(false), which causes policy to be reloaded when a domain changes state. + - Reloading the policy does not work on older versions of the C(policycoreutils-python) library, for example in EL 6.". type: bool default: false store: @@ -47,18 +46,18 @@ options: type: str default: '' notes: - - Requires a recent version of SELinux and C(policycoreutils-python) (EL 6 or newer). -requirements: [ policycoreutils-python ] + - Requires a recent version of SELinux and C(policycoreutils-python) (EL 6 or newer). +requirements: [policycoreutils-python] author: -- Michael Scherer (@mscherer) -''' + - Michael Scherer (@mscherer) +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Change the httpd_t domain to permissive community.general.selinux_permissive: name: httpd_t permissive: true -''' +""" import traceback diff --git a/plugins/modules/selogin.py b/plugins/modules/selogin.py index 57482b0908..8f1b20c230 100644 --- a/plugins/modules/selogin.py +++ b/plugins/modules/selogin.py @@ -8,12 +8,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: selogin short_description: Manages linux user to SELinux user mapping description: - - Manages linux user to SELinux user mapping + - Manages linux user to SELinux user mapping. extends_documentation_fragment: - community.general.attributes attributes: @@ -25,15 +24,15 @@ options: login: type: str description: - - a Linux user + - A Linux user. required: true seuser: type: str description: - - SELinux user name + - SELinux user name. selevel: type: str - aliases: [ serange ] + aliases: [serange] description: - MLS/MCS Security Range (MLS/MCS Systems only) SELinux Range for SELinux login mapping defaults to the SELinux user record range. default: s0 @@ -42,7 +41,7 @@ options: description: - Desired mapping value. default: present - choices: [ 'present', 'absent' ] + choices: ['present', 'absent'] reload: description: - Reload SELinux policy after commit. @@ -50,20 +49,20 @@ options: default: true ignore_selinux_state: description: - - Run independent of selinux runtime state + - Run independent of selinux runtime state. type: bool default: false notes: - - The changes are persistent across reboots - - Not tested on any debian based system -requirements: [ 'libselinux', 'policycoreutils' ] + - The changes are persistent across reboots. + - Not tested on any debian based system. +requirements: ['libselinux', 'policycoreutils'] author: -- Dan Keder (@dankeder) -- Petr Lautrbach (@bachradsusi) -- James Cassell (@jamescassell) -''' + - Dan Keder (@dankeder) + - Petr Lautrbach (@bachradsusi) + - James Cassell (@jamescassell) +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Modify the default user on the system to the guest_u user community.general.selogin: login: __default__ @@ -82,11 +81,11 @@ EXAMPLES = ''' login: '%engineering' seuser: staff_u state: present -''' +""" -RETURN = r''' +RETURN = r""" # Default return values -''' +""" import traceback diff --git a/plugins/modules/sendgrid.py b/plugins/modules/sendgrid.py index b4f6b6eaff..c964fa8c23 100644 --- a/plugins/modules/sendgrid.py +++ b/plugins/modules/sendgrid.py @@ -9,21 +9,15 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: sendgrid short_description: Sends an email with the SendGrid API description: - - "Sends an email with a SendGrid account through their API, not through - the SMTP service." + - Sends an email with a SendGrid account through their API, not through the SMTP service. notes: - - "This module is non-idempotent because it sends an email through the - external API. It is idempotent only in the case that the module fails." - - "Like the other notification modules, this one requires an external - dependency to work. In this case, you'll need an active SendGrid - account." - - "In order to use api_key, cc, bcc, attachments, from_name, html_body, headers - you must pip install sendgrid" + - This module is non-idempotent because it sends an email through the external API. It is idempotent only in the case that the module fails. + - Like the other notification modules, this one requires an external dependency to work. In this case, you will need an active SendGrid account. + - In order to use O(api_key), O(cc), O(bcc), O(attachments), O(from_name), O(html_body), and O(headers) you must C(pip install sendgrid). requirements: - sendgrid Python library 1.6.22 or lower (Sendgrid API V2 supported) extends_documentation_fragment: @@ -98,9 +92,9 @@ options: - The e-mail body content. required: true author: "Matt Makai (@makaimc)" -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Send an email to a single recipient that the deployment was successful community.general.sendgrid: username: "{{ sendgrid_username }}" @@ -114,16 +108,16 @@ EXAMPLES = r''' - name: Send an email to more than one recipient that the build failed community.general.sendgrid: - username: "{{ sendgrid_username }}" - password: "{{ sendgrid_password }}" - from_address: "build@mycompany.com" - to_addresses: - - "ops@mycompany.com" - - "devteam@mycompany.com" - subject: "Build failure!." - body: "Unable to pull source repository from Git server." + username: "{{ sendgrid_username }}" + password: "{{ sendgrid_password }}" + from_address: "build@mycompany.com" + to_addresses: + - "ops@mycompany.com" + - "devteam@mycompany.com" + subject: "Build failure!." + body: "Unable to pull source repository from Git server." delegate_to: localhost -''' +""" # ======================================= # sendgrid module support methods diff --git a/plugins/modules/sensu_check.py b/plugins/modules/sensu_check.py index 1430d6a6ce..018bb75db3 100644 --- a/plugins/modules/sensu_check.py +++ b/plugins/modules/sensu_check.py @@ -9,15 +9,14 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: sensu_check short_description: Manage Sensu checks description: - Manage the checks that should be run on a machine by I(Sensu). - Most options do not have a default and will not be added to the check definition unless specified. - All defaults except O(path), O(state), O(backup) and O(metric) are not managed by this module, - - they are simply specified for your convenience. + they are simply specified for your convenience. extends_documentation_fragment: - community.general.attributes attributes: @@ -29,127 +28,127 @@ options: name: type: str description: - - The name of the check - - This is the key that is used to determine whether a check exists + - The name of the check. + - This is the key that is used to determine whether a check exists. required: true state: type: str description: - - Whether the check should be present or not - choices: [ 'present', 'absent' ] + - Whether the check should be present or not. + choices: ['present', 'absent'] default: present path: type: str description: - Path to the json file of the check to be added/removed. - Will be created if it does not exist (unless O(state=absent)). - - The parent folders need to exist when O(state=present), otherwise an error will be thrown + - The parent folders need to exist when O(state=present), otherwise an error will be thrown. default: /etc/sensu/conf.d/checks.json backup: description: - Create a backup file (if yes), including the timestamp information so - - you can get the original file back if you somehow clobbered it incorrectly. + you can get the original file back if you somehow clobbered it incorrectly. type: bool default: false command: type: str description: - - Path to the sensu check to run (not required when O(state=absent)) + - Path to the sensu check to run (not required when O(state=absent)). handlers: type: list elements: str description: - - List of handlers to notify when the check fails + - List of handlers to notify when the check fails. subscribers: type: list elements: str description: - - List of subscribers/channels this check should run for - - See sensu_subscribers to subscribe a machine to a channel + - List of subscribers/channels this check should run for. + - See sensu_subscribers to subscribe a machine to a channel. interval: type: int description: - - Check interval in seconds + - Check interval in seconds. timeout: type: int description: - - Timeout for the check + - Timeout for the check. - If not specified, it defaults to 10. ttl: type: int description: - - Time to live in seconds until the check is considered stale + - Time to live in seconds until the check is considered stale. handle: description: - - Whether the check should be handled or not + - Whether the check should be handled or not. - Default is V(false). type: bool subdue_begin: type: str description: - - When to disable handling of check failures + - When to disable handling of check failures. subdue_end: type: str description: - - When to enable handling of check failures + - When to enable handling of check failures. dependencies: type: list elements: str description: - - Other checks this check depends on, if dependencies fail handling of this check will be disabled + - Other checks this check depends on, if dependencies fail handling of this check will be disabled. metric: description: - - Whether the check is a metric + - Whether the check is a metric. type: bool default: false standalone: description: - - Whether the check should be scheduled by the sensu client or server - - This option obviates the need for specifying the O(subscribers) option + - Whether the check should be scheduled by the sensu client or server. + - This option obviates the need for specifying the O(subscribers) option. - Default is V(false). type: bool publish: description: - Whether the check should be scheduled at all. - - You can still issue it via the sensu api + - You can still issue it via the sensu API. - Default is V(false). type: bool occurrences: type: int description: - - Number of event occurrences before the handler should take action + - Number of event occurrences before the handler should take action. - If not specified, defaults to 1. refresh: type: int description: - - Number of seconds handlers should wait before taking second action + - Number of seconds handlers should wait before taking second action. aggregate: description: - Classifies the check as an aggregate check, - - making it available via the aggregate API + making it available via the aggregate API. - Default is V(false). type: bool low_flap_threshold: type: int description: - - The low threshold for flap detection + - The low threshold for flap detection. high_flap_threshold: type: int description: - - The high threshold for flap detection + - The high threshold for flap detection. custom: type: dict description: - A hash/dictionary of custom parameters for mixing to the configuration. - - You can't rewrite others module parameters using this + - You can't rewrite others module parameters using this. source: type: str description: - The check source, used to create a JIT Sensu client for an external resource (e.g. a network switch). author: "Anders Ingemann (@andsens)" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" # Fetch metrics about the CPU load every 60 seconds, # the sensu server has a handler called 'relay' which forwards stats to graphite - name: Get cpu metrics @@ -177,7 +176,7 @@ EXAMPLES = ''' community.general.sensu_check: name: check_disk_capacity state: absent -''' +""" import json import traceback diff --git a/plugins/modules/sensu_client.py b/plugins/modules/sensu_client.py index eca0804b0a..0de0340f33 100644 --- a/plugins/modules/sensu_client.py +++ b/plugins/modules/sensu_client.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: sensu_client author: "David Moreau Simard (@dmsimard)" short_description: Manages Sensu client configuration @@ -27,8 +26,8 @@ options: state: type: str description: - - Whether the client should be present or not - choices: [ 'present', 'absent' ] + - Whether the client should be present or not. + choices: ['present', 'absent'] default: present name: type: str @@ -49,7 +48,8 @@ options: - The subscriptions array items must be strings. safe_mode: description: - - If safe mode is enabled for the client. Safe mode requires local check definitions in order to accept a check request and execute the check. + - If safe mode is enabled for the client. Safe mode requires local check definitions in order to accept a check request and execute the + check. type: bool default: false redact: @@ -99,11 +99,9 @@ options: type: dict description: - The servicenow definition scope, used to configure the Sensu Enterprise ServiceNow integration (Sensu Enterprise users only). -notes: - - Check mode is supported -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" # Minimum possible configuration - name: Configure Sensu client community.general.sensu_client: @@ -146,20 +144,20 @@ EXAMPLES = ''' - name: Delete the Sensu client configuration community.general.sensu_client: state: "absent" -''' +""" -RETURN = ''' +RETURN = r""" config: - description: Effective client configuration, when state is present + description: Effective client configuration, when state is present. returned: success type: dict sample: {'name': 'client', 'subscriptions': ['default']} file: - description: Path to the client configuration file + description: Path to the client configuration file. returned: success type: str sample: "/etc/sensu/conf.d/client.json" -''' +""" import json import os diff --git a/plugins/modules/sensu_handler.py b/plugins/modules/sensu_handler.py index bbb8dc6129..bd1014f2dd 100644 --- a/plugins/modules/sensu_handler.py +++ b/plugins/modules/sensu_handler.py @@ -8,13 +8,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: sensu_handler author: "David Moreau Simard (@dmsimard)" short_description: Manages Sensu handler configuration description: - - Manages Sensu handler configuration + - Manages Sensu handler configuration. - 'For more information, refer to the Sensu documentation: U(https://sensuapp.org/docs/latest/reference/handlers.html)' extends_documentation_fragment: - community.general.attributes @@ -27,8 +26,8 @@ options: state: type: str description: - - Whether the handler should be present or not - choices: [ 'present', 'absent' ] + - Whether the handler should be present or not. + choices: ['present', 'absent'] default: present name: type: str @@ -38,8 +37,8 @@ options: type: type: str description: - - The handler type - choices: [ 'pipe', 'tcp', 'udp', 'transport', 'set' ] + - The handler type. + choices: ['pipe', 'tcp', 'udp', 'transport', 'set'] filter: type: str description: @@ -98,12 +97,10 @@ options: elements: str description: - An array of Sensu event handlers (names) to use for events using the handler set. - - 'NOTE: the handlers attribute is only required for handler sets (i.e. handlers configured with "type": "set").' -notes: - - Check mode is supported -''' + - 'NOTE: the handlers attribute is only required for handler sets (that is, handlers configured with O(type=set)).' +""" -EXAMPLES = ''' +EXAMPLES = r""" # Configure a handler that sends event data as STDIN (pipe) - name: Configure IRC Sensu handler community.general.sensu_handler: @@ -146,25 +143,25 @@ EXAMPLES = ''' owner: "sensu" group: "sensu" mode: "0600" -''' +""" -RETURN = ''' +RETURN = r""" config: - description: Effective handler configuration, when state is present + description: Effective handler configuration, when state is present. returned: success type: dict sample: {'name': 'irc', 'type': 'pipe', 'command': '/usr/local/bin/notify-irc.sh'} file: - description: Path to the handler configuration file + description: Path to the handler configuration file. returned: success type: str sample: "/etc/sensu/conf.d/handlers/irc.json" name: - description: Name of the handler + description: Name of the handler. returned: success type: str sample: "irc" -''' +""" import json import os diff --git a/plugins/modules/sensu_silence.py b/plugins/modules/sensu_silence.py index 25dfc239eb..bcb70f9bd1 100644 --- a/plugins/modules/sensu_silence.py +++ b/plugins/modules/sensu_silence.py @@ -9,14 +9,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: sensu_silence author: Steven Bambling (@smbambling) short_description: Manage Sensu silence entries description: - - Create and clear (delete) a silence entries via the Sensu API - for subscriptions and checks. + - Create and clear (delete) a silence entries via the Sensu API for subscriptions and checks. extends_documentation_fragment: - community.general.attributes attributes: @@ -36,30 +34,26 @@ options: expire: type: int description: - - If specified, the silence entry will be automatically cleared - after this number of seconds. + - If specified, the silence entry will be automatically cleared after this number of seconds. expire_on_resolve: description: - - If specified as true, the silence entry will be automatically - cleared once the condition it is silencing is resolved. + - If specified as true, the silence entry will be automatically cleared once the condition it is silencing is resolved. type: bool reason: type: str description: - - If specified, this free-form string is used to provide context or - rationale for the reason this silence entry was created. + - If specified, this free-form string is used to provide context or rationale for the reason this silence entry was created. state: type: str description: - - Specifies to create or clear (delete) a silence entry via the Sensu API + - Specifies to create or clear (delete) a silence entry via the Sensu API. default: present choices: ['present', 'absent'] subscription: type: str description: - Specifies the subscription which the silence entry applies to. - - To create a silence entry for a client prepend C(client:) to client name. - Example - C(client:server1.example.dev) + - To create a silence entry for a client prepend C(client:) to client name. Example - C(client:server1.example.dev). required: true url: type: str @@ -67,9 +61,9 @@ options: - Specifies the URL of the Sensu monitoring host server. required: false default: http://127.0.01:4567 -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" # Silence ALL checks for a given client - name: Silence server1.example.dev community.general.sensu_silence: @@ -98,10 +92,10 @@ EXAMPLES = ''' reason: "{{ item.value.reason }}" creator: "{{ ansible_user_id }}" with_dict: "{{ silence }}" -''' +""" -RETURN = ''' -''' +RETURN = r""" +""" import json diff --git a/plugins/modules/sensu_subscription.py b/plugins/modules/sensu_subscription.py index 0077e2ffa6..e7c78c3290 100644 --- a/plugins/modules/sensu_subscription.py +++ b/plugins/modules/sensu_subscription.py @@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: sensu_subscription short_description: Manage Sensu subscriptions description: - - Manage which I(sensu channels) a machine should subscribe to + - Manage which I(sensu channels) a machine should subscribe to. extends_documentation_fragment: - community.general.attributes attributes: @@ -26,41 +25,41 @@ options: name: type: str description: - - The name of the channel + - The name of the channel. required: true state: type: str description: - - Whether the machine should subscribe or unsubscribe from the channel - choices: [ 'present', 'absent' ] + - Whether the machine should subscribe or unsubscribe from the channel. + choices: ['present', 'absent'] required: false default: present path: type: str description: - - Path to the subscriptions json file + - Path to the subscriptions json file. required: false default: /etc/sensu/conf.d/subscriptions.json backup: description: - Create a backup file (if yes), including the timestamp information so you - - can get the original file back if you somehow clobbered it incorrectly. + can get the original file back if you somehow clobbered it incorrectly. type: bool required: false default: false -requirements: [ ] +requirements: [] author: Anders Ingemann (@andsens) -''' +""" -RETURN = ''' +RETURN = r""" reasons: - description: the reasons why the module changed or did not change something - returned: success - type: list - sample: ["channel subscription was absent and state is `present'"] -''' + description: The reasons why the module changed or did not change something. + returned: success + type: list + sample: ["channel subscription was absent and state is `present'"] +""" -EXAMPLES = ''' +EXAMPLES = r""" # Subscribe to the nginx channel - name: Subscribe to nginx checks community.general.sensu_subscription: name=nginx @@ -68,7 +67,7 @@ EXAMPLES = ''' # Unsubscribe from the common checks channel - name: Unsubscribe from common checks community.general.sensu_subscription: name=common state=absent -''' +""" import json import traceback diff --git a/plugins/modules/seport.py b/plugins/modules/seport.py index 964e8f0eda..24311fc56d 100644 --- a/plugins/modules/seport.py +++ b/plugins/modules/seport.py @@ -8,14 +8,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: seport short_description: Manages SELinux network port type definitions description: - - Manages SELinux network port type definitions. + - Manages SELinux network port type definitions. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: full @@ -34,7 +33,7 @@ options: - Protocol for the specified port. type: str required: true - choices: [ tcp, udp ] + choices: [tcp, udp] setype: description: - SELinux type for the specified port. @@ -44,7 +43,7 @@ options: description: - Desired boolean value. type: str - choices: [ absent, present ] + choices: [absent, present] default: present reload: description: @@ -53,26 +52,26 @@ options: default: true ignore_selinux_state: description: - - Run independent of selinux runtime state + - Run independent of selinux runtime state. type: bool default: false local: description: - - Work with local modifications only. + - Work with local modifications only. type: bool default: false version_added: 5.6.0 notes: - - The changes are persistent across reboots. - - Not tested on any debian based system. + - The changes are persistent across reboots. + - Not tested on any Debian based system. requirements: -- libselinux-python -- policycoreutils-python + - libselinux-python + - policycoreutils-python author: -- Dan Keder (@dankeder) -''' + - Dan Keder (@dankeder) +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Allow Apache to listen on tcp port 8888 community.general.seport: ports: 8888 @@ -110,7 +109,7 @@ EXAMPLES = r''' setype: ssh_port_t state: absent local: true -''' +""" import traceback diff --git a/plugins/modules/serverless.py b/plugins/modules/serverless.py index 8aa9396d62..937f7dcdea 100644 --- a/plugins/modules/serverless.py +++ b/plugins/modules/serverless.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: serverless short_description: Manages a Serverless Framework project description: @@ -26,11 +25,11 @@ options: description: - Goal state of given stage/project. type: str - choices: [ absent, present ] + choices: [absent, present] default: present serverless_bin_path: description: - - The path of a serverless framework binary relative to the 'service_path' eg. node_module/.bin/serverless + - The path of a serverless framework binary relative to the O(service_path), for example V(node_module/.bin/serverless). type: path service_path: description: @@ -67,16 +66,15 @@ options: type: bool default: false notes: - - Currently, the C(serverless) command must be in the path of the node executing the task. - In the future this may be a flag. + - Currently, the C(serverless) command must be in the path of the node executing the task. In the future this may be a flag. requirements: -- serverless -- yaml + - serverless + - PyYAML author: -- Ryan Scott Brown (@ryansb) -''' + - Ryan Scott Brown (@ryansb) +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Basic deploy of a service community.general.serverless: service_path: '{{ project_dir }}' @@ -103,9 +101,9 @@ EXAMPLES = r''' region: us-east-1 service_path: '{{ project_dir }}' serverless_bin_path: node_modules/.bin/serverless -''' +""" -RETURN = r''' +RETURN = r""" service_name: type: str description: The service name specified in the serverless.yml that was just deployed. @@ -120,7 +118,7 @@ command: description: Full C(serverless) command run by this module, in case you want to re-run the command outside the module. returned: always sample: serverless deploy --stage production -''' +""" import os diff --git a/plugins/modules/shutdown.py b/plugins/modules/shutdown.py index d8108425eb..6f2dac14b1 100644 --- a/plugins/modules/shutdown.py +++ b/plugins/modules/shutdown.py @@ -8,14 +8,14 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' +DOCUMENTATION = r""" module: shutdown short_description: Shut down a machine notes: - - E(PATH) is ignored on the remote node when searching for the C(shutdown) command. Use O(search_paths) - to specify locations to search if the default paths do not work. - - The O(msg) and O(delay) options are not supported when a shutdown command is not found in O(search_paths), instead - the module will attempt to shutdown the system by calling C(systemctl shutdown). + - E(PATH) is ignored on the remote node when searching for the C(shutdown) command. Use O(search_paths) to specify locations to search if the + default paths do not work. + - The O(msg) and O(delay) options are not supported when a shutdown command is not found in O(search_paths), instead the module will attempt + to shutdown the system by calling C(systemctl shutdown). description: - Shut downs a machine. version_added: "1.1.0" @@ -47,20 +47,21 @@ options: search_paths: description: - Paths to search on the remote machine for the C(shutdown) command. - - I(Only) these paths will be searched for the C(shutdown) command. E(PATH) is ignored in the remote node when searching for the C(shutdown) command. + - I(Only) these paths will be searched for the C(shutdown) command. E(PATH) is ignored in the remote node when searching for the C(shutdown) + command. type: list elements: path default: ['/sbin', '/usr/sbin', '/usr/local/sbin'] seealso: -- module: ansible.builtin.reboot + - module: ansible.builtin.reboot author: - - Matt Davis (@nitzmahone) - - Sam Doran (@samdoran) - - Amin Vakil (@aminvakil) -''' + - Matt Davis (@nitzmahone) + - Sam Doran (@samdoran) + - Amin Vakil (@aminvakil) +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Unconditionally shut down the machine with all defaults community.general.shutdown: @@ -71,13 +72,13 @@ EXAMPLES = r''' - name: Shut down a machine with shutdown command in unusual place community.general.shutdown: search_paths: - - '/lib/molly-guard' -''' + - '/lib/molly-guard' +""" -RETURN = r''' +RETURN = r""" shutdown: description: V(true) if the machine has been shut down. returned: always type: bool sample: true -''' +""" diff --git a/plugins/modules/simpleinit_msb.py b/plugins/modules/simpleinit_msb.py index 92738471c2..2b1b865d2c 100644 --- a/plugins/modules/simpleinit_msb.py +++ b/plugins/modules/simpleinit_msb.py @@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: simpleinit_msb short_description: Manage services on Source Mage GNU/Linux version_added: 7.5.0 @@ -38,24 +37,21 @@ options: state: type: str required: false - choices: [ running, started, stopped, restarted, reloaded ] + choices: [running, started, stopped, restarted, reloaded] description: - - V(started)/V(stopped) are idempotent actions that will not run - commands unless necessary. V(restarted) will always bounce the - service. V(reloaded) will always reload. + - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary. V(restarted) will always bounce the service. + V(reloaded) will always reload. - At least one of O(state) and O(enabled) are required. - - Note that V(reloaded) will start the - service if it is not already started, even if your chosen init - system would not normally. + - Note that V(reloaded) will start the service if it is not already started, even if your chosen init system would not normally. enabled: type: bool required: false description: - Whether the service should start on boot. - At least one of O(state) and O(enabled) are required. -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Example action to start service httpd, if not running community.general.simpleinit_msb: name: httpd @@ -80,7 +76,7 @@ EXAMPLES = ''' community.general.simpleinit_msb: name: httpd enabled: true -''' +""" import os import re diff --git a/plugins/modules/sl_vm.py b/plugins/modules/sl_vm.py index 1604ffc11f..3216fded8b 100644 --- a/plugins/modules/sl_vm.py +++ b/plugins/modules/sl_vm.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: sl_vm short_description: Create or cancel a virtual instance in SoftLayer description: @@ -121,7 +120,7 @@ options: disks: description: - List of disk sizes to be assigned to new virtual instance. - default: [ 25 ] + default: [25] type: list elements: int os_code: @@ -159,7 +158,7 @@ options: description: - Create, or cancel a virtual instance. - Specify V(present) for create, V(absent) to cancel. - choices: [ absent, present ] + choices: [absent, present] default: present type: str wait: @@ -173,102 +172,102 @@ options: default: 600 type: int requirements: - - softlayer >= 4.1.1 + - softlayer >= 4.1.1 author: -- Matt Colton (@mcltn) -''' + - Matt Colton (@mcltn) +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Build instance hosts: localhost gather_facts: false tasks: - - name: Build instance request - community.general.sl_vm: - hostname: instance-1 - domain: anydomain.com - datacenter: dal09 - tags: ansible-module-test - hourly: true - private: false - dedicated: false - local_disk: true - cpus: 1 - memory: 1024 - disks: [25] - os_code: UBUNTU_LATEST - wait: false + - name: Build instance request + community.general.sl_vm: + hostname: instance-1 + domain: anydomain.com + datacenter: dal09 + tags: ansible-module-test + hourly: true + private: false + dedicated: false + local_disk: true + cpus: 1 + memory: 1024 + disks: [25] + os_code: UBUNTU_LATEST + wait: false - name: Build additional instances hosts: localhost gather_facts: false tasks: - - name: Build instances request - community.general.sl_vm: - hostname: "{{ item.hostname }}" - domain: "{{ item.domain }}" - datacenter: "{{ item.datacenter }}" - tags: "{{ item.tags }}" - hourly: "{{ item.hourly }}" - private: "{{ item.private }}" - dedicated: "{{ item.dedicated }}" - local_disk: "{{ item.local_disk }}" - cpus: "{{ item.cpus }}" - memory: "{{ item.memory }}" - disks: "{{ item.disks }}" - os_code: "{{ item.os_code }}" - ssh_keys: "{{ item.ssh_keys }}" - wait: "{{ item.wait }}" - with_items: - - hostname: instance-2 - domain: anydomain.com - datacenter: dal09 - tags: - - ansible-module-test - - ansible-module-test-replicas - hourly: true - private: false - dedicated: false - local_disk: true - cpus: 1 - memory: 1024 - disks: - - 25 - - 100 - os_code: UBUNTU_LATEST - ssh_keys: [] - wait: true - - hostname: instance-3 - domain: anydomain.com - datacenter: dal09 - tags: - - ansible-module-test - - ansible-module-test-replicas - hourly: true - private: false - dedicated: false - local_disk: true - cpus: 1 - memory: 1024 - disks: - - 25 - - 100 - os_code: UBUNTU_LATEST - ssh_keys: [] - wait: true + - name: Build instances request + community.general.sl_vm: + hostname: "{{ item.hostname }}" + domain: "{{ item.domain }}" + datacenter: "{{ item.datacenter }}" + tags: "{{ item.tags }}" + hourly: "{{ item.hourly }}" + private: "{{ item.private }}" + dedicated: "{{ item.dedicated }}" + local_disk: "{{ item.local_disk }}" + cpus: "{{ item.cpus }}" + memory: "{{ item.memory }}" + disks: "{{ item.disks }}" + os_code: "{{ item.os_code }}" + ssh_keys: "{{ item.ssh_keys }}" + wait: "{{ item.wait }}" + with_items: + - hostname: instance-2 + domain: anydomain.com + datacenter: dal09 + tags: + - ansible-module-test + - ansible-module-test-replicas + hourly: true + private: false + dedicated: false + local_disk: true + cpus: 1 + memory: 1024 + disks: + - 25 + - 100 + os_code: UBUNTU_LATEST + ssh_keys: [] + wait: true + - hostname: instance-3 + domain: anydomain.com + datacenter: dal09 + tags: + - ansible-module-test + - ansible-module-test-replicas + hourly: true + private: false + dedicated: false + local_disk: true + cpus: 1 + memory: 1024 + disks: + - 25 + - 100 + os_code: UBUNTU_LATEST + ssh_keys: [] + wait: true - name: Cancel instances hosts: localhost gather_facts: false tasks: - - name: Cancel by tag - community.general.sl_vm: - state: absent - tags: ansible-module-test -''' + - name: Cancel by tag + community.general.sl_vm: + state: absent + tags: ansible-module-test +""" # TODO: Disabled RETURN as it is breaking the build for docs. Needs to be fixed. -RETURN = '''# ''' +RETURN = """# """ import json import time diff --git a/plugins/modules/slack.py b/plugins/modules/slack.py index 58893b0f42..b4e637f591 100644 --- a/plugins/modules/slack.py +++ b/plugins/modules/slack.py @@ -15,11 +15,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ +DOCUMENTATION = r""" module: slack short_description: Send Slack notifications description: - - The M(community.general.slack) module sends notifications to U(http://slack.com) via the Incoming WebHook integration + - The M(community.general.slack) module sends notifications to U(http://slack.com) via the Incoming WebHook integration. author: "Ramon de la Fuente (@ramondelafuente)" extends_documentation_fragment: - community.general.attributes @@ -32,51 +32,42 @@ options: domain: type: str description: - - Slack (sub)domain for your environment without protocol. (For example - V(example.slack.com).) In Ansible 1.8 and beyond, this is deprecated and may - be ignored. See token documentation for information. + - Slack (sub)domain for your environment without protocol. (For example V(example.slack.com).) In Ansible 1.8 and beyond, this is deprecated + and may be ignored. See token documentation for information. token: type: str description: - - Slack integration token. This authenticates you to the slack service. - Make sure to use the correct type of token, depending on what method you use. - - "Webhook token: - Prior to Ansible 1.8, a token looked like V(3Ffe373sfhRE6y42Fg3rvf4GlK). In - Ansible 1.8 and above, Ansible adapts to the new slack API where tokens look - like V(G922VJP24/D921DW937/3Ffe373sfhRE6y42Fg3rvf4GlK). If tokens - are in the new format then slack will ignore any value of domain. If - the token is in the old format the domain is required. Ansible has no - control of when slack will get rid of the old API. When slack does - that the old format will stop working. ** Please keep in mind the tokens - are not the API tokens but are the webhook tokens. In slack these are - found in the webhook URL which are obtained under the apps and integrations. - The incoming webhooks can be added in that area. In some cases this may - be locked by your Slack admin and you must request access. It is there - that the incoming webhooks can be added. The key is on the end of the - URL given to you in that section." - - "WebAPI token: - Slack WebAPI requires a personal, bot or work application token. These tokens start with V(xoxp-), V(xoxb-) - or V(xoxa-), for example V(xoxb-1234-56789abcdefghijklmnop). WebAPI token is required if you intend to receive thread_id. - See Slack's documentation (U(https://api.slack.com/docs/token-types)) for more information." + - Slack integration token. This authenticates you to the slack service. Make sure to use the correct type of token, depending on what method + you use. + - 'Webhook token: Prior to Ansible 1.8, a token looked like V(3Ffe373sfhRE6y42Fg3rvf4GlK). In Ansible 1.8 and above, Ansible adapts to the + new slack API where tokens look like V(G922VJP24/D921DW937/3Ffe373sfhRE6y42Fg3rvf4GlK). If tokens are in the new format then slack will + ignore any value of domain. If the token is in the old format the domain is required. Ansible has no control of when slack will get rid + of the old API. When slack does that the old format will stop working. ** Please keep in mind the tokens are not the API tokens but are + the webhook tokens. In slack these are found in the webhook URL which are obtained under the apps and integrations. The incoming webhooks + can be added in that area. In some cases this may be locked by your Slack admin and you must request access. It is there that the incoming + webhooks can be added. The key is on the end of the URL given to you in that section.' + - "WebAPI token: Slack WebAPI requires a personal, bot or work application token. These tokens start with V(xoxp-), V(xoxb-) or V(xoxa-), + for example V(xoxb-1234-56789abcdefghijklmnop). WebAPI token is required if you intend to receive thread_id. See Slack's documentation + (U(https://api.slack.com/docs/token-types)) for more information." required: true msg: type: str description: - - Message to send. Note that the module does not handle escaping characters. - Plain-text angle brackets and ampersands should be converted to HTML entities (e.g. & to &) before sending. - See Slack's documentation (U(https://api.slack.com/docs/message-formatting)) for more. + - Message to send. Note that the module does not handle escaping characters. Plain-text angle brackets and ampersands should be converted + to HTML entities (for example C(&) to C(&)) before sending. See Slack's documentation (U(https://api.slack.com/docs/message-formatting)) for more. channel: type: str description: - Channel to send the message to. If absent, the message goes to the channel selected for the O(token). thread_id: description: - - Optional. Timestamp of parent message to thread this message. https://api.slack.com/docs/message-threading + - Optional. Timestamp of parent message to thread this message, see U(https://api.slack.com/docs/message-threading). type: str message_id: description: - Optional. Message ID to edit, instead of posting a new message. - - If supplied O(channel) must be in form of C(C0xxxxxxx). use C({{ slack_response.channel }}) to get RV(ignore:channel) from previous task run. + - If supplied O(channel) must be in form of C(C0xxxxxxx). use C({{ slack_response.channel }}) to get RV(ignore:channel) from previous task + run. - The token needs history scope to get information on the message to edit (C(channels:history,groups:history,mpim:history,im:history)). - Corresponds to C(ts) in the Slack API (U(https://api.slack.com/messaging/modifying)). type: str @@ -107,14 +98,13 @@ options: parse: type: str description: - - Setting for the message parser at Slack + - Setting for the message parser at Slack. choices: - 'full' - 'none' validate_certs: description: - - If V(false), SSL certificates will not be validated. This should only be used - on personally controlled sites using self-signed certificates. + - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates. type: bool default: true color: @@ -140,11 +130,10 @@ options: type: str description: - Setting for automatically prepending a V(#) symbol on the passed in O(channel). - - The V(auto) method prepends a V(#) unless O(channel) starts with one of V(#), V(@), V(C0), V(GF), V(G0), V(CP). - These prefixes only cover a small set of the prefixes that should not have a V(#) prepended. - Since an exact condition which O(channel) values must not have the V(#) prefix is not known, - the value V(auto) for this option will be deprecated in the future. It is best to explicitly set - O(prepend_hash=always) or O(prepend_hash=never) to obtain the needed behavior. + - The V(auto) method prepends a V(#) unless O(channel) starts with one of V(#), V(@), V(C0), V(GF), V(G0), V(CP). These prefixes only cover + a small set of the prefixes that should not have a V(#) prepended. Since an exact condition which O(channel) values must not have the + V(#) prefix is not known, the value V(auto) for this option will be deprecated in the future. It is best to explicitly set O(prepend_hash=always) + or O(prepend_hash=never) to obtain the needed behavior. choices: - 'always' - 'never' @@ -153,7 +142,7 @@ options: version_added: 6.1.0 """ -EXAMPLES = """ +EXAMPLES = r""" - name: Send notification message via Slack community.general.slack: token: thetoken/generatedby/slack @@ -215,14 +204,14 @@ EXAMPLES = """ Display my system load on host A and B - type: context elements: - - type: mrkdwn - text: |- - *System A* - load average: 0,74, 0,66, 0,63 - - type: mrkdwn - text: |- - *System B* - load average: 5,16, 4,64, 2,43 + - type: mrkdwn + text: |- + *System A* + load average: 0,74, 0,66, 0,63 + - type: mrkdwn + text: |- + *System B* + load average: 5,16, 4,64, 2,43 - name: Send a message with a link using Slack markup community.general.slack: diff --git a/plugins/modules/slackpkg.py b/plugins/modules/slackpkg.py index 9347db1591..2ec91de051 100644 --- a/plugins/modules/slackpkg.py +++ b/plugins/modules/slackpkg.py @@ -15,49 +15,47 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: slackpkg short_description: Package manager for Slackware >= 12.2 description: - - Manage binary packages for Slackware using 'slackpkg' which - is available in versions after 12.2. + - Manage binary packages for Slackware using C(slackpkg) which is available in versions after 12.2. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - name: - description: - - name of package to install/remove - required: true - type: list - elements: str - aliases: [pkg] + name: + description: + - Name of package to install/remove. + required: true + type: list + elements: str + aliases: [pkg] - state: - description: - - State of the package, you can use V(installed) as an alias for V(present) and V(removed) as one for V(absent). - choices: [ 'present', 'absent', 'latest', 'installed', 'removed' ] - required: false - default: present - type: str + state: + description: + - State of the package, you can use V(installed) as an alias for V(present) and V(removed) as one for V(absent). + choices: ['present', 'absent', 'latest', 'installed', 'removed'] + required: false + default: present + type: str - update_cache: - description: - - update the package database first - required: false - default: false - type: bool + update_cache: + description: + - Update the package database first. + required: false + default: false + type: bool author: Kim Nørgaard (@KimNorgaard) -requirements: [ "Slackware >= 12.2" ] -''' +requirements: ["Slackware >= 12.2"] +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install package foo community.general.slackpkg: name: foo @@ -72,7 +70,7 @@ EXAMPLES = ''' community.general.slackpkg: name: foo state: latest -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/smartos_image_info.py b/plugins/modules/smartos_image_info.py index 1a25b46681..96bf9b0575 100644 --- a/plugins/modules/smartos_image_info.py +++ b/plugins/modules/smartos_image_info.py @@ -9,31 +9,28 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: smartos_image_info short_description: Get SmartOS image details description: - - Retrieve information about all installed images on SmartOS. + - Retrieve information about all installed images on SmartOS. author: Adam Števko (@xen0l) extends_documentation_fragment: - - community.general.attributes - - community.general.attributes.info_module + - community.general.attributes + - community.general.attributes.info_module attributes: - check_mode: - version_added: 3.3.0 - # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix + check_mode: + version_added: 3.3.0 + # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix options: - filters: - description: - - Criteria for selecting image. Can be any value from image - manifest and C(published_date), C(published), C(source), C(clones), - and C(size). More information can be found at U(https://smartos.org/man/1m/imgadm) - under C(imgadm list). - type: str -''' + filters: + description: + - Criteria for selecting image. Can be any value from image manifest and V(published_date), V(published), V(source), V(clones), and V(size). + - More information can be found at U(https://smartos.org/man/1m/imgadm) under C(imgadm list). + type: str +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Return information about all installed images community.general.smartos_image_info: register: result @@ -49,19 +46,17 @@ EXAMPLES = ''' - name: Print information ansible.builtin.debug: - msg: "{{ result.smartos_images[item]['name'] }}-{{ result.smartos_images[item]['version'] }} - has {{ result.smartos_images[item]['clones'] }} VM(s)" + msg: "{{ result.smartos_images[item]['name'] }}-{{ result.smartos_images[item]['version'] }} has {{ result.smartos_images[item]['clones'] }} VM(s)" with_items: "{{ result.smartos_images.keys() | list }}" - name: Print information ansible.builtin.debug: - msg: "{{ smartos_images[item]['name'] }}-{{ smartos_images[item]['version'] }} - has {{ smartos_images[item]['clones'] }} VM(s)" + msg: "{{ smartos_images[item]['name'] }}-{{ smartos_images[item]['version'] }} has {{ smartos_images[item]['clones'] }} VM(s)" with_items: "{{ smartos_images.keys() | list }}" -''' +""" -RETURN = ''' -''' +RETURN = r""" +""" import json from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/snap.py b/plugins/modules/snap.py index 15637f3315..1de829801d 100644 --- a/plugins/modules/snap.py +++ b/plugins/modules/snap.py @@ -13,96 +13,87 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: snap short_description: Manages snaps description: - - Manages snaps packages. + - Manages snaps packages. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - name: - description: - - Name of the snaps to be installed. - - Any named snap accepted by the C(snap) command is valid. - - > - O(dangerous=true) may be necessary when installing `.snap` files. See O(dangerous) for more details. - required: true - type: list - elements: str - state: - description: - - Desired state of the package. - - > - When O(state=present) the module will use C(snap install) if the snap is not installed, - and C(snap refresh) if it is installed but from a different channel. - default: present - choices: [ absent, present, enabled, disabled ] - type: str - classic: - description: - - Install a snap that has classic confinement. - - This option corresponds to the C(--classic) argument of the C(snap install) command. - - This level of confinement is permissive, granting full system access, - similar to that of traditionally packaged applications that do not use sandboxing mechanisms. - This option can only be specified when the task involves a single snap. - - See U(https://snapcraft.io/docs/snap-confinement) for more details about classic confinement and confinement levels. - - type: bool - required: false - default: false - channel: - description: - - Define which release of a snap is installed and tracked for updates. - This option can only be specified if there is a single snap in the task. - - If not passed, the C(snap) command will default to V(stable). - - If the value passed does not contain the C(track), it will default to C(latest). - For example, if V(edge) is passed, the module will assume the channel to be V(latest/edge). - - See U(https://snapcraft.io/docs/channels) for more details about snap channels. - type: str - required: false - options: - description: - - Set options with pattern C(key=value) or C(snap:key=value). If a snap name is given, the option will be applied - to that snap only. If the snap name is omitted, the options will be applied to all snaps listed in O(name). Options will - only be applied to active snaps. - - Options will only be applied when C(state) is set to V(present). - This is done after the necessary installation - or refresh (upgrade/downgrade) of all the snaps listed in O(name). - - See U(https://snapcraft.io/docs/configuration-in-snaps) for more details about snap configuration options. - - required: false - type: list - elements: str - version_added: 4.4.0 - dangerous: - description: - - Install the snap in dangerous mode, without validating its assertions and signatures. - - This is useful when installing local snaps that are either unsigned or have signatures that have not been acknowledged. - - See U(https://snapcraft.io/docs/install-modes) for more details about installation modes. - type: bool - required: false - default: false - version_added: 7.2.0 + name: + description: + - Name of the snaps to be installed. + - Any named snap accepted by the C(snap) command is valid. + - O(dangerous=true) may be necessary when installing C(.snap) files. See O(dangerous) for more details. + required: true + type: list + elements: str + state: + description: + - Desired state of the package. + - When O(state=present) the module will use C(snap install) if the snap is not installed, and C(snap refresh) if it is installed but from + a different channel. + default: present + choices: [absent, present, enabled, disabled] + type: str + classic: + description: + - Install a snap that has classic confinement. + - This option corresponds to the C(--classic) argument of the C(snap install) command. + - This level of confinement is permissive, granting full system access, similar to that of traditionally packaged applications that do not + use sandboxing mechanisms. This option can only be specified when the task involves a single snap. + - See U(https://snapcraft.io/docs/snap-confinement) for more details about classic confinement and confinement levels. + type: bool + required: false + default: false + channel: + description: + - Define which release of a snap is installed and tracked for updates. This option can only be specified if there is a single snap in the + task. + - If not passed, the C(snap) command will default to V(stable). + - If the value passed does not contain the C(track), it will default to C(latest). For example, if V(edge) is passed, the module will assume + the channel to be V(latest/edge). + - See U(https://snapcraft.io/docs/channels) for more details about snap channels. + type: str + required: false + options: + description: + - Set options with pattern C(key=value) or C(snap:key=value). If a snap name is given, the option will be applied to that snap only. If + the snap name is omitted, the options will be applied to all snaps listed in O(name). Options will only be applied to active snaps. + - Options will only be applied when C(state) is set to V(present). This is done after the necessary installation or refresh (upgrade/downgrade) + of all the snaps listed in O(name). + - See U(https://snapcraft.io/docs/configuration-in-snaps) for more details about snap configuration options. + required: false + type: list + elements: str + version_added: 4.4.0 + dangerous: + description: + - Install the snap in dangerous mode, without validating its assertions and signatures. + - This is useful when installing local snaps that are either unsigned or have signatures that have not been acknowledged. + - See U(https://snapcraft.io/docs/install-modes) for more details about installation modes. + type: bool + required: false + default: false + version_added: 7.2.0 notes: - - Privileged operations, such as installing and configuring snaps, require root priviledges. - This is only the case if the user has not logged in to the Snap Store. - + - Privileged operations, such as installing and configuring snaps, require root priviledges. This is only the case if the user has not logged + in to the Snap Store. author: - - Victor Carceler (@vcarceler) - - Stanislas Lange (@angristan) + - Victor Carceler (@vcarceler) + - Stanislas Lange (@angristan) seealso: - - module: community.general.snap_alias -''' + - module: community.general.snap_alias +""" -EXAMPLES = ''' +EXAMPLES = r""" # Install "foo" and "bar" snap - name: Install foo community.general.snap: @@ -147,35 +138,35 @@ EXAMPLES = ''' community.general.snap: name: foo channel: latest/edge -''' +""" -RETURN = ''' +RETURN = r""" classic: - description: Whether or not the snaps were installed with the classic confinement - type: bool - returned: When snaps are installed + description: Whether or not the snaps were installed with the classic confinement. + type: bool + returned: When snaps are installed channel: - description: The channel the snaps were installed from - type: str - returned: When snaps are installed + description: The channel the snaps were installed from. + type: str + returned: When snaps are installed cmd: - description: The command that was executed on the host - type: str - returned: When changed is true + description: The command that was executed on the host. + type: str + returned: When changed is true snaps_installed: - description: The list of actually installed snaps - type: list - returned: When any snaps have been installed + description: The list of actually installed snaps. + type: list + returned: When any snaps have been installed snaps_removed: - description: The list of actually removed snaps - type: list - returned: When any snaps have been removed + description: The list of actually removed snaps. + type: list + returned: When any snaps have been removed options_changed: - description: The list of options set/changed in format C(snap:key=value). - type: list - returned: When any options have been changed/set - version_added: 4.4.0 -''' + description: The list of options set/changed in format C(snap:key=value). + type: list + returned: When any options have been changed/set + version_added: 4.4.0 +""" import re import json diff --git a/plugins/modules/snap_alias.py b/plugins/modules/snap_alias.py index ba54a9e155..81a968730d 100644 --- a/plugins/modules/snap_alias.py +++ b/plugins/modules/snap_alias.py @@ -9,46 +9,45 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: snap_alias short_description: Manages snap aliases version_added: 4.0.0 description: - - "Manages snaps aliases." + - Manages snaps aliases. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: full + check_mode: + support: full + diff_mode: + support: full options: - state: - description: - - Desired state of the alias. - type: str - choices: [ absent, present ] - default: present - name: - description: - - Name of the snap. - type: str - alias: - description: - - Aliases to be created or removed. - type: list - elements: str - aliases: [aliases] + state: + description: + - Desired state of the alias. + type: str + choices: [absent, present] + default: present + name: + description: + - Name of the snap. + type: str + alias: + description: + - Aliases to be created or removed. + type: list + elements: str + aliases: [aliases] author: - - Alexei Znamensky (@russoz) + - Alexei Znamensky (@russoz) seealso: - - module: community.general.snap -''' + - module: community.general.snap +""" -EXAMPLES = ''' +EXAMPLES = r""" # Install "foo" and "bar" snap - name: Create snap alias community.general.snap_alias: @@ -62,7 +61,7 @@ EXAMPLES = ''' - hw - hw2 - hw3 - state: present # optional + state: present # optional - name: Remove one specific aliases community.general.snap_alias: @@ -73,15 +72,15 @@ EXAMPLES = ''' community.general.snap_alias: name: hello-world state: absent -''' +""" -RETURN = ''' +RETURN = r""" snap_aliases: - description: The snap aliases after execution. If called in check mode, then the list represents the state before execution. - type: list - elements: str - returned: always -''' + description: The snap aliases after execution. If called in check mode, then the list represents the state before execution. + type: list + elements: str + returned: always +""" import re diff --git a/plugins/modules/snmp_facts.py b/plugins/modules/snmp_facts.py index d561f93f02..af0abf9479 100644 --- a/plugins/modules/snmp_facts.py +++ b/plugins/modules/snmp_facts.py @@ -9,87 +9,85 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: snmp_facts author: -- Patrick Ogenstad (@ogenstad) + - Patrick Ogenstad (@ogenstad) short_description: Retrieve facts for a device using SNMP description: - - Retrieve facts for a device using SNMP, the facts will be - inserted to the ansible_facts key. + - Retrieve facts for a device using SNMP, the facts will be inserted to the C(ansible_facts) key. requirements: - - pysnmp + - pysnmp extends_documentation_fragment: - - community.general.attributes - - community.general.attributes.facts - - community.general.attributes.facts_module + - community.general.attributes + - community.general.attributes.facts + - community.general.attributes.facts_module attributes: - check_mode: - version_added: 3.3.0 - # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix + check_mode: + version_added: 3.3.0 + # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix options: - host: - description: - - Set to target SNMP server (normally C({{ inventory_hostname }})). - type: str - required: true - version: - description: - - SNMP Version to use, V(v2), V(v2c) or V(v3). - type: str - required: true - choices: [ v2, v2c, v3 ] - community: - description: - - The SNMP community string, required if O(version) is V(v2) or V(v2c). - type: str - level: - description: - - Authentication level. - - Required if O(version=v3). - type: str - choices: [ authNoPriv, authPriv ] - username: - description: - - Username for SNMPv3. - - Required if O(version=v3). - type: str - integrity: - description: - - Hashing algorithm. - - Required if O(version=v3). - type: str - choices: [ md5, sha ] - authkey: - description: - - Authentication key. - - Required O(version=v3). - type: str - privacy: - description: - - Encryption algorithm. - - Required if O(level=authPriv). - type: str - choices: [ aes, des ] - privkey: - description: - - Encryption key. - - Required if O(level=authPriv). - type: str - timeout: - description: - - Response timeout in seconds. - type: int - version_added: 2.3.0 - retries: - description: - - Maximum number of request retries, 0 retries means just a single request. - type: int - version_added: 2.3.0 -''' + host: + description: + - Set to target SNMP server (normally C({{ inventory_hostname }})). + type: str + required: true + version: + description: + - SNMP Version to use, V(v2), V(v2c) or V(v3). + type: str + required: true + choices: [v2, v2c, v3] + community: + description: + - The SNMP community string, required if O(version) is V(v2) or V(v2c). + type: str + level: + description: + - Authentication level. + - Required if O(version=v3). + type: str + choices: [authNoPriv, authPriv] + username: + description: + - Username for SNMPv3. + - Required if O(version=v3). + type: str + integrity: + description: + - Hashing algorithm. + - Required if O(version=v3). + type: str + choices: [md5, sha] + authkey: + description: + - Authentication key. + - Required O(version=v3). + type: str + privacy: + description: + - Encryption algorithm. + - Required if O(level=authPriv). + type: str + choices: [aes, des] + privkey: + description: + - Encryption key. + - Required if O(level=authPriv). + type: str + timeout: + description: + - Response timeout in seconds. + type: int + version_added: 2.3.0 + retries: + description: + - Maximum number of request retries, 0 retries means just a single request. + type: int + version_added: 2.3.0 +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Gather facts with SNMP version 2 community.general.snmp_facts: host: '{{ inventory_hostname }}' @@ -108,9 +106,9 @@ EXAMPLES = r''' authkey: abc12345 privkey: def6789 delegate_to: localhost -''' +""" -RETURN = r''' +RETURN = r""" ansible_sysdescr: description: A textual description of the entity. returned: success @@ -152,39 +150,39 @@ ansible_interfaces: type: dict sample: { "1": { - "adminstatus": "up", - "description": "", - "ifindex": "1", - "ipv4": [ - { - "address": "127.0.0.1", - "netmask": "255.0.0.0" - } - ], - "mac": "", - "mtu": "65536", - "name": "lo", - "operstatus": "up", - "speed": "65536" + "adminstatus": "up", + "description": "", + "ifindex": "1", + "ipv4": [ + { + "address": "127.0.0.1", + "netmask": "255.0.0.0" + } + ], + "mac": "", + "mtu": "65536", + "name": "lo", + "operstatus": "up", + "speed": "65536" }, "2": { - "adminstatus": "up", - "description": "", - "ifindex": "2", - "ipv4": [ - { - "address": "192.168.213.128", - "netmask": "255.255.255.0" - } - ], - "mac": "000a305a52a1", - "mtu": "1500", - "name": "Intel Corporation 82545EM Gigabit Ethernet Controller (Copper)", - "operstatus": "up", - "speed": "1500" + "adminstatus": "up", + "description": "", + "ifindex": "2", + "ipv4": [ + { + "address": "192.168.213.128", + "netmask": "255.255.255.0" + } + ], + "mac": "000a305a52a1", + "mtu": "1500", + "name": "Intel Corporation 82545EM Gigabit Ethernet Controller (Copper)", + "operstatus": "up", + "speed": "1500" } } -''' +""" import binascii from collections import defaultdict