From 9e91fb0704de59f937a7acd8e8372e92255465aa Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sun, 27 Jul 2025 14:34:24 +0000 Subject: [PATCH] [PR #10480/c1bd4611 backport][stable-11] doc style adjustments: modules s* (#10487) doc style adjustments: modules s* (#10480) * doc style adjustments: modules s* * adjust comment indentation * remove empty RETURN section in stacki_host * spectrum_model_attrs: improve formatting of example * Apply suggestions from code review * Update plugins/modules/spotinst_aws_elastigroup.py * Update plugins/modules/swdepot.py --------- (cherry picked from commit c1bd461173168336a255bb3cca3d533129b13a3e) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> Co-authored-by: Felix Fontein --- plugins/modules/say.py | 3 +- plugins/modules/scaleway_compute.py | 2 +- plugins/modules/scaleway_container.py | 4 +- .../modules/scaleway_container_namespace.py | 2 +- .../modules/scaleway_container_registry.py | 2 +- plugins/modules/scaleway_function.py | 2 +- .../modules/scaleway_function_namespace.py | 2 +- plugins/modules/scaleway_image_info.py | 2 +- plugins/modules/scaleway_ip_info.py | 4 +- plugins/modules/scaleway_organization_info.py | 2 +- .../modules/scaleway_security_group_info.py | 2 +- plugins/modules/scaleway_server_info.py | 2 +- plugins/modules/scaleway_snapshot_info.py | 2 +- plugins/modules/scaleway_volume_info.py | 2 +- plugins/modules/selinux_permissive.py | 2 +- plugins/modules/selogin.py | 3 +- plugins/modules/sendgrid.py | 6 +-- plugins/modules/sensu_check.py | 9 ++-- plugins/modules/sensu_client.py | 14 ++++-- plugins/modules/sensu_handler.py | 11 +++-- plugins/modules/sensu_silence.py | 4 +- plugins/modules/serverless.py | 2 +- plugins/modules/slack.py | 43 ++++++++++--------- plugins/modules/smartos_image_info.py | 12 +++++- plugins/modules/snap.py | 20 ++++----- plugins/modules/snmp_facts.py | 2 +- plugins/modules/solaris_zone.py | 4 +- plugins/modules/sorcery.py | 4 +- plugins/modules/spectrum_device.py | 19 +++++--- plugins/modules/spectrum_model_attrs.py | 8 ++-- plugins/modules/spotinst_aws_elastigroup.py | 37 ++++++++-------- plugins/modules/ss_3par_cpg.py | 7 +-- plugins/modules/ssh_config.py | 39 +++++++++-------- plugins/modules/stacki_host.py | 19 -------- plugins/modules/statusio_maintenance.py | 2 +- plugins/modules/sudoers.py | 12 +++--- plugins/modules/supervisorctl.py | 15 +++---- plugins/modules/svc.py | 8 ++-- plugins/modules/svr4pkg.py | 2 +- plugins/modules/swdepot.py | 2 +- plugins/modules/systemd_info.py | 19 ++++---- plugins/modules/sysupgrade.py | 7 ++- 42 files changed, 191 insertions(+), 174 deletions(-) diff --git a/plugins/modules/say.py b/plugins/modules/say.py index 2dc359083d..5be37e6f20 100644 --- a/plugins/modules/say.py +++ b/plugins/modules/say.py @@ -17,7 +17,8 @@ description: notes: - In 2.5, this module has been renamed from C(osx_say) to M(community.general.say). - If you like this module, you may also be interested in the osx_say callback plugin. - - A list of available voices, with language, can be found by running C(say -v ?) on a OSX host and C(espeak --voices) on a Linux host. + - A list of available voices, with language, can be found by running C(say -v ?) on a OSX host and C(espeak --voices) on + a Linux host. extends_documentation_fragment: - community.general.attributes attributes: diff --git a/plugins/modules/scaleway_compute.py b/plugins/modules/scaleway_compute.py index c61030bede..f3653cd3b6 100644 --- a/plugins/modules/scaleway_compute.py +++ b/plugins/modules/scaleway_compute.py @@ -133,7 +133,7 @@ options: type: str description: - Security group unique identifier. - - If no value provided, the default security group or current security group will be used. + - If no value provided, the default security group or current security group is used. required: false """ diff --git a/plugins/modules/scaleway_container.py b/plugins/modules/scaleway_container.py index dc4df1c1d5..8351660fd6 100644 --- a/plugins/modules/scaleway_container.py +++ b/plugins/modules/scaleway_container.py @@ -89,7 +89,7 @@ options: secret_environment_variables: description: - Secret environment variables of the container namespace. - - Updating those values will not output a C(changed) state in Ansible. + - Updating those values does not output a C(changed) state in Ansible. - Injected in container at runtime. type: dict default: {} @@ -125,7 +125,7 @@ options: max_concurrency: description: - Maximum number of connections per container. - - This parameter will be used to trigger autoscaling. + - This parameter is used to trigger autoscaling. type: int protocol: diff --git a/plugins/modules/scaleway_container_namespace.py b/plugins/modules/scaleway_container_namespace.py index 802a491321..781c9ffc25 100644 --- a/plugins/modules/scaleway_container_namespace.py +++ b/plugins/modules/scaleway_container_namespace.py @@ -79,7 +79,7 @@ options: secret_environment_variables: description: - Secret environment variables of the container namespace. - - Updating those values will not output a C(changed) state in Ansible. + - Updating those values does not output a C(changed) state in Ansible. - Injected in containers at runtime. type: dict default: {} diff --git a/plugins/modules/scaleway_container_registry.py b/plugins/modules/scaleway_container_registry.py index 132dfe8bb6..4e352c5b9e 100644 --- a/plugins/modules/scaleway_container_registry.py +++ b/plugins/modules/scaleway_container_registry.py @@ -71,7 +71,7 @@ options: type: str description: - Default visibility policy. - - Everyone will be able to pull images from a V(public) registry. + - Everyone can pull images from a V(public) registry. choices: - public - private diff --git a/plugins/modules/scaleway_function.py b/plugins/modules/scaleway_function.py index e2142dd1f2..4bc7c42688 100644 --- a/plugins/modules/scaleway_function.py +++ b/plugins/modules/scaleway_function.py @@ -89,7 +89,7 @@ options: secret_environment_variables: description: - Secret environment variables of the function. - - Updating those values will not output a C(changed) state in Ansible. + - Updating those values does not output a C(changed) state in Ansible. - Injected in function at runtime. type: dict default: {} diff --git a/plugins/modules/scaleway_function_namespace.py b/plugins/modules/scaleway_function_namespace.py index d43b42bc7f..e5e00bf681 100644 --- a/plugins/modules/scaleway_function_namespace.py +++ b/plugins/modules/scaleway_function_namespace.py @@ -79,7 +79,7 @@ options: secret_environment_variables: description: - Secret environment variables of the function namespace. - - Updating those values will not output a C(changed) state in Ansible. + - Updating those values does not output a C(changed) state in Ansible. - Injected in functions at runtime. type: dict default: {} diff --git a/plugins/modules/scaleway_image_info.py b/plugins/modules/scaleway_image_info.py index 44474218db..0b2fe0476d 100644 --- a/plugins/modules/scaleway_image_info.py +++ b/plugins/modules/scaleway_image_info.py @@ -57,7 +57,7 @@ scaleway_image_info: type: list elements: dict sample: - "scaleway_image_info": [ + [ { "arch": "x86_64", "creation_date": "2018-07-17T16:18:49.276456+00:00", diff --git a/plugins/modules/scaleway_ip_info.py b/plugins/modules/scaleway_ip_info.py index 8b2a78449e..0812746619 100644 --- a/plugins/modules/scaleway_ip_info.py +++ b/plugins/modules/scaleway_ip_info.py @@ -52,12 +52,12 @@ RETURN = r""" scaleway_ip_info: description: - Response from Scaleway API. - - 'For more details please refer to U(https://developers.scaleway.com/en/products/instance/api/).' + - For more details please refer to U(https://developers.scaleway.com/en/products/instance/api/). returned: success type: list elements: dict sample: - "scaleway_ip_info": [ + [ { "address": "163.172.170.243", "id": "ea081794-a581-8899-8451-386ddaf0a451", diff --git a/plugins/modules/scaleway_organization_info.py b/plugins/modules/scaleway_organization_info.py index 0aeabb94fd..a28b290bbc 100644 --- a/plugins/modules/scaleway_organization_info.py +++ b/plugins/modules/scaleway_organization_info.py @@ -44,7 +44,7 @@ scaleway_organization_info: type: list elements: dict sample: - "scaleway_organization_info": [ + [ { "address_city_name": "Paris", "address_country_code": "FR", diff --git a/plugins/modules/scaleway_security_group_info.py b/plugins/modules/scaleway_security_group_info.py index 04eb2da0d1..4cdb295282 100644 --- a/plugins/modules/scaleway_security_group_info.py +++ b/plugins/modules/scaleway_security_group_info.py @@ -56,7 +56,7 @@ scaleway_security_group_info: type: list elements: dict sample: - "scaleway_security_group_info": [ + [ { "description": "test-ams", "enable_default_security": true, diff --git a/plugins/modules/scaleway_server_info.py b/plugins/modules/scaleway_server_info.py index 8f4cbc6a2c..327715d2db 100644 --- a/plugins/modules/scaleway_server_info.py +++ b/plugins/modules/scaleway_server_info.py @@ -57,7 +57,7 @@ scaleway_server_info: type: list elements: dict sample: - "scaleway_server_info": [ + [ { "arch": "x86_64", "boot_type": "local", diff --git a/plugins/modules/scaleway_snapshot_info.py b/plugins/modules/scaleway_snapshot_info.py index ae6c3b532f..ead1826aa4 100644 --- a/plugins/modules/scaleway_snapshot_info.py +++ b/plugins/modules/scaleway_snapshot_info.py @@ -57,7 +57,7 @@ scaleway_snapshot_info: type: list elements: dict sample: - "scaleway_snapshot_info": [ + [ { "base_volume": { "id": "68386fae-4f55-4fbf-aabb-953036a85872", diff --git a/plugins/modules/scaleway_volume_info.py b/plugins/modules/scaleway_volume_info.py index c8e2cd1302..8a4986a724 100644 --- a/plugins/modules/scaleway_volume_info.py +++ b/plugins/modules/scaleway_volume_info.py @@ -57,7 +57,7 @@ scaleway_volume_info: type: list elements: dict sample: - "scaleway_volume_info": [ + [ { "creation_date": "2018-08-14T20:56:24.949660+00:00", "export_uri": null, diff --git a/plugins/modules/selinux_permissive.py b/plugins/modules/selinux_permissive.py index b5c0ee4a61..c6107309ac 100644 --- a/plugins/modules/selinux_permissive.py +++ b/plugins/modules/selinux_permissive.py @@ -24,7 +24,7 @@ attributes: options: domain: description: - - The domain that will be added or removed from the list of permissive domains. + - The domain that is added or removed from the list of permissive domains. type: str required: true aliases: [name] diff --git a/plugins/modules/selogin.py b/plugins/modules/selogin.py index 8f1b20c230..408d9221da 100644 --- a/plugins/modules/selogin.py +++ b/plugins/modules/selogin.py @@ -34,7 +34,8 @@ options: type: str aliases: [serange] description: - - MLS/MCS Security Range (MLS/MCS Systems only) SELinux Range for SELinux login mapping defaults to the SELinux user record range. + - MLS/MCS Security Range (MLS/MCS Systems only) SELinux Range for SELinux login mapping defaults to the SELinux user + record range. default: s0 state: type: str diff --git a/plugins/modules/sendgrid.py b/plugins/modules/sendgrid.py index 1099f579e1..ba2562d90c 100644 --- a/plugins/modules/sendgrid.py +++ b/plugins/modules/sendgrid.py @@ -17,8 +17,8 @@ description: 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 will need an - active SendGrid account. + - Like the other notification modules, this one requires an external dependency to work. In this case, you 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: @@ -82,7 +82,7 @@ options: - The name you want to appear in the from field, for example V(John Doe). html_body: description: - - Whether the body is html content that should be rendered. + - Whether the body is HTML content that should be rendered. type: bool default: false headers: diff --git a/plugins/modules/sensu_check.py b/plugins/modules/sensu_check.py index 2cac434923..a4b5771528 100644 --- a/plugins/modules/sensu_check.py +++ b/plugins/modules/sensu_check.py @@ -14,7 +14,7 @@ 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. + - Most options do not have a default and are not 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. deprecated: @@ -45,8 +45,8 @@ options: 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. + - It is created if it does not exist (unless O(state=absent)). + - The parent folders need to exist when O(state=present), otherwise an error is thrown. default: /etc/sensu/conf.d/checks.json backup: description: @@ -99,7 +99,8 @@ options: type: list elements: str description: - - Other checks this check depends on, if dependencies fail handling of this check will be disabled. + - Other checks this one depends on. + - If dependencies fail handling of this check is disabled. metric: description: - Whether the check is a metric. diff --git a/plugins/modules/sensu_client.py b/plugins/modules/sensu_client.py index 955a25f44f..f87621bd6d 100644 --- a/plugins/modules/sensu_client.py +++ b/plugins/modules/sensu_client.py @@ -14,7 +14,7 @@ author: "David Moreau Simard (@dmsimard)" short_description: Manages Sensu client configuration description: - Manages Sensu client configuration. - - 'For more information, refer to the L(Sensu documentation, https://sensuapp.org/docs/latest/reference/clients.html).' + - For more information, refer to the L(Sensu documentation, https://sensuapp.org/docs/latest/reference/clients.html). deprecated: removed_in: 13.0.0 why: Sensu Core and Sensu Enterprise products have been End of Life since 2019/20. @@ -42,8 +42,8 @@ options: type: str description: - An address to help identify and reach the client. This is only informational, usually an IP address or hostname. - - If not specified it defaults to non-loopback IPv4 address as determined by Ruby C(Socket.ip_address_list) (provided by - Sensu). + - If not specified it defaults to non-loopback IPv4 address as determined by Ruby C(Socket.ip_address_list) (provided + by Sensu). subscriptions: type: list elements: str @@ -158,7 +158,13 @@ config: description: Effective client configuration, when state is present. returned: success type: dict - sample: {'name': 'client', 'subscriptions': ['default']} + sample: + { + "name": "client", + "subscriptions": [ + "default" + ] + } file: description: Path to the client configuration file. returned: success diff --git a/plugins/modules/sensu_handler.py b/plugins/modules/sensu_handler.py index ff4a77a6ff..5b5494bf1c 100644 --- a/plugins/modules/sensu_handler.py +++ b/plugins/modules/sensu_handler.py @@ -14,7 +14,7 @@ author: "David Moreau Simard (@dmsimard)" short_description: Manages Sensu handler configuration description: - Manages Sensu handler configuration. - - 'For more information, refer to the L(Sensu documentation, https://sensuapp.org/docs/latest/reference/handlers.html).' + - For more information, refer to the L(Sensu documentation, https://sensuapp.org/docs/latest/reference/handlers.html). deprecated: removed_in: 13.0.0 why: Sensu Core and Sensu Enterprise products have been End of Life since 2019/20. @@ -57,7 +57,7 @@ options: type: list elements: str description: - - An array of check result severities the handler will handle. + - An array of check result severities the handler handles. - 'NOTE: event resolution bypasses this filtering.' - "Example: [ 'warning', 'critical', 'unknown' ]." mutator: @@ -155,7 +155,12 @@ config: description: Effective handler configuration, when state is present. returned: success type: dict - sample: {'name': 'irc', 'type': 'pipe', 'command': '/usr/local/bin/notify-irc.sh'} + sample: + { + "name": "irc", + "type": "pipe", + "command": "/usr/local/bin/notify-irc.sh" + } file: description: Path to the handler configuration file. returned: success diff --git a/plugins/modules/sensu_silence.py b/plugins/modules/sensu_silence.py index b030dc4e69..12a5f872b9 100644 --- a/plugins/modules/sensu_silence.py +++ b/plugins/modules/sensu_silence.py @@ -38,10 +38,10 @@ options: expire: type: int description: - - If specified, the silence entry will be automatically cleared after this number of seconds. + - If specified, the silence entry is 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 is automatically cleared once the condition it is silencing is resolved. type: bool reason: type: str diff --git a/plugins/modules/serverless.py b/plugins/modules/serverless.py index 937f7dcdea..8bba307440 100644 --- a/plugins/modules/serverless.py +++ b/plugins/modules/serverless.py @@ -51,7 +51,7 @@ options: deploy: description: - Whether or not to deploy artifacts after building them. - - When this option is V(false) all the functions will be built, but no stack update will be run to send them out. + - When this option is V(false) all the functions are built, but no stack update is run to send them out. - This is mostly useful for generating artifacts to be stored/deployed elsewhere. type: bool default: true diff --git a/plugins/modules/slack.py b/plugins/modules/slack.py index f1c375c31b..e009320d85 100644 --- a/plugins/modules/slack.py +++ b/plugins/modules/slack.py @@ -32,23 +32,24 @@ options: domain: type: str description: - - "When using new format 'Webhook token' and WebAPI tokens: this can be V(slack.com) or V(slack-gov.com) and is ignored otherwise." + - "When using new format 'Webhook token' and WebAPI tokens: this can be V(slack.com) or V(slack-gov.com) and is ignored + otherwise." - "When using old format 'Webhook token': 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." + 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, + - 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 except V(slack.com) or V(slack-gov.com). 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.' + Ansible adapts to the new Slack API where tokens look like V(G922VJP24/D921DW937/3Ffe373sfhRE6y42Fg3rvf4GlK). If tokens + are in the new format then Slack ignores any value of domain except V(slack.com) or V(slack-gov.com). If the token + is in the old format the domain is required. Ansible has no control of when Slack is going to remove the old API. + When Slack does that the old format is going to cease working. B(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." @@ -58,7 +59,8 @@ options: 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 (for example C(&) to C(&)) before sending. See Slack's documentation - (U(https://api.slack.com/docs/message-formatting)) for more. + (U(https://api.slack.com/docs/message-formatting)) + for more. channel: type: str description: @@ -90,7 +92,7 @@ options: type: str description: - Emoji for the message sender. See Slack documentation for options. - - If O(icon_emoji) is set, O(icon_url) will not be used. + - If O(icon_emoji) is set, O(icon_url) is not used. link_names: type: int description: @@ -108,8 +110,8 @@ options: - '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 are not validated. This should only be used on personally controlled sites using self-signed + certificates. type: bool default: true color: @@ -139,11 +141,12 @@ options: - 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 B(current default) is V(auto), which has been B(deprecated) since community.general 10.2.0. It will change to - V(never) in community.general 12.0.0. To prevent deprecation warnings you can explicitly set O(prepend_hash) to the - value you want. We suggest to only use V(always) or V(never), but not V(auto), when explicitly setting a value. + O(channel) values must not have the V(#) prefix is not known, the value V(auto) for this option is 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 B(current default) is V(auto), which has been B(deprecated) since community.general 10.2.0. It is going to change + to V(never) in community.general 12.0.0. To prevent deprecation warnings you can explicitly set O(prepend_hash) to + the value you want. We suggest to only use V(always) or V(never), but not V(auto), when explicitly setting a value. + # when the default changes in community.general 12.0.0, add deprecation for the `auto` value for 14.0.0 choices: - 'always' - 'never' diff --git a/plugins/modules/smartos_image_info.py b/plugins/modules/smartos_image_info.py index 19ad740b72..89c00f5c26 100644 --- a/plugins/modules/smartos_image_info.py +++ b/plugins/modules/smartos_image_info.py @@ -47,12 +47,20 @@ EXAMPLES = r""" - 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 }}" """ diff --git a/plugins/modules/snap.py b/plugins/modules/snap.py index 3ffe9642fa..fd424e0dd9 100644 --- a/plugins/modules/snap.py +++ b/plugins/modules/snap.py @@ -37,8 +37,8 @@ options: 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. + - When O(state=present) the module uses 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 @@ -56,19 +56,19 @@ options: 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). + - If not passed, the C(snap) command defaults to V(stable). + - If the value passed does not contain the C(track), it defaults to C(latest). For example, if V(edge) is passed, the + module assumes 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). + - Set options with pattern C(key=value) or C(snap:key=value). If a snap name is given, the option is applied to that + snap only. If the snap name is omitted, the options are applied to all snaps listed in O(name). Options are only applied + to active snaps. + - Options are only 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 diff --git a/plugins/modules/snmp_facts.py b/plugins/modules/snmp_facts.py index a87e1d33a1..17c7bbd032 100644 --- a/plugins/modules/snmp_facts.py +++ b/plugins/modules/snmp_facts.py @@ -15,7 +15,7 @@ author: - 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 C(ansible_facts) key. + - Retrieve facts for a device using SNMP, the facts are inserted to the C(ansible_facts) key. requirements: - pysnmp extends_documentation_fragment: diff --git a/plugins/modules/solaris_zone.py b/plugins/modules/solaris_zone.py index 31e7919c08..431e0cb31d 100644 --- a/plugins/modules/solaris_zone.py +++ b/plugins/modules/solaris_zone.py @@ -51,7 +51,7 @@ options: required: true path: description: - - The path where the zone will be created. This is required when the zone is created, but not used otherwise. + - The path where the zone is created. This is required when the zone is created, but not used otherwise. type: str sparse: description: @@ -60,7 +60,7 @@ options: default: false root_password: description: - - The password hash for the root account. If not specified, the zone's root account will not have a password. + - The password hash for the root account. If not specified, the zone's root account does not have a password. type: str config: description: diff --git a/plugins/modules/sorcery.py b/plugins/modules/sorcery.py index fff3f55e07..8af9b6bc18 100644 --- a/plugins/modules/sorcery.py +++ b/plugins/modules/sorcery.py @@ -34,7 +34,7 @@ options: description: - Name of the spell or grimoire. - Multiple names can be given, separated by commas. - - Special value V(*) in conjunction with states V(latest) or V(rebuild) will update or rebuild the whole system respectively. + - Special value V(*) in conjunction with states V(latest) or V(rebuild) updates or rebuilds the whole system respectively. - The alias O(grimoire) was added in community.general 7.3.0. aliases: ["spell", "grimoire"] type: list @@ -44,7 +44,7 @@ options: description: - Repository location. - If specified, O(name) represents grimoire(s) instead of spell(s). - - Special value V(*) will pull grimoire from the official location. + - Special value V(*) pulls grimoire from the official location. - Only single item in O(name) in conjunction with V(*) can be used. - O(state=absent) must be used with a special value V(*). type: str diff --git a/plugins/modules/spectrum_device.py b/plugins/modules/spectrum_device.py index 8bf4aa41b5..54cddbffb0 100644 --- a/plugins/modules/spectrum_device.py +++ b/plugins/modules/spectrum_device.py @@ -30,7 +30,7 @@ options: required: true description: - IP address of the device. - - If a hostname is given, it will be resolved to the IP address. + - If a hostname is given, it is resolved to the IP address. community: type: str description: @@ -69,13 +69,13 @@ options: - Oneclick user password. use_proxy: description: - - If V(false), it will not use a proxy, even if one is defined in an environment variable on the target hosts. + - If V(false), it does not use a proxy, even if one is defined in an environment variable on the target hosts. default: true type: bool 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 are not validated. This should only be used on personally controlled sites using self-signed + certificates. default: true type: bool agentport: @@ -85,8 +85,8 @@ options: - UDP port used for SNMP discovery. default: 161 notes: - - The devices will be created inside the I(Universe) container of the specified landscape. - - All the operations will be performed only on the specified landscape. + - The devices are created inside the I(Universe) container of the specified landscape. + - All the operations are performed only on the specified landscape. """ EXAMPLES = r""" @@ -119,7 +119,12 @@ device: description: Device data when O(state=present). returned: success type: dict - sample: {'model_handle': '0x1007ab', 'landscape': '0x100000', 'address': '10.10.5.1'} + sample: + { + "model_handle": "0x1007ab", + "landscape": "0x100000", + "address": "10.10.5.1" + } """ from socket import gethostbyname, gaierror diff --git a/plugins/modules/spectrum_model_attrs.py b/plugins/modules/spectrum_model_attrs.py index 9c9fba4deb..53cae10b74 100644 --- a/plugins/modules/spectrum_model_attrs.py +++ b/plugins/modules/spectrum_model_attrs.py @@ -47,7 +47,7 @@ options: aliases: [password] use_proxy: description: - - If V(false), it will not use a proxy, even if one is defined in an environment variable on the target hosts. + - If V(false), it does not use a proxy, even if one is defined in an environment variable on the target hosts. default: true required: false type: bool @@ -99,7 +99,7 @@ options: - C(sysName) (C(0x10b5b)); - C(Vendor_Name) (C(0x11570)); - C(Description) (C(0x230017)). - - Hex IDs are the direct identifiers in Spectrum and will always work. + - Hex IDs are the direct identifiers in Spectrum and always work. - 'To lookup hex IDs go to the UI: Locator -> Devices -> By Model Name -> -> Attributes tab.' type: str required: true @@ -123,7 +123,9 @@ EXAMPLES = r""" - name: "isManaged" value: "false" - name: "Notes" - value: "MM set on {{ ansible_date_time.iso8601 }} via CO {{ CO }} by {{ tower_user_name | default(ansible_user_id) }}" + value: >- + MM set on {{ ansible_date_time.iso8601 }} via CO {{ CO }} + by {{ tower_user_name | default(ansible_user_id) }} delegate_to: localhost register: spectrum_model_attrs_status """ diff --git a/plugins/modules/spotinst_aws_elastigroup.py b/plugins/modules/spotinst_aws_elastigroup.py index 9aa14afd8d..759a094626 100644 --- a/plugins/modules/spotinst_aws_elastigroup.py +++ b/plugins/modules/spotinst_aws_elastigroup.py @@ -11,9 +11,9 @@ short_description: Create, update or delete Spotinst AWS Elastigroups author: Spotinst (@talzur) description: - Can create, update, or delete Spotinst AWS Elastigroups Launch configuration is part of the elastigroup configuration, - so no additional modules are necessary for handling the launch configuration. You will have to have a credentials file - in this location - C($HOME/.spotinst/credentials). The credentials file must contain a row that looks like this C(token - = ). + so no additional modules are necessary for handling the launch configuration. You must have a credentials file in this + location - C($HOME/.spotinst/credentials). The credentials file must contain a row that looks like this C(token = ). - Full documentation available at U(https://help.spotinst.com/hc/en-us/articles/115003530285-Ansible-). requirements: - spotinst_sdk >= 1.0.38 @@ -41,8 +41,8 @@ options: token: description: - A Personal API Access Token issued by Spotinst. - - 'When not specified, the module will try to obtain it, in that order, from: environment variable E(SPOTINST_TOKEN), - or from the credentials path.' + - When not specified, the module tries to obtain it, in that order, from environment variable E(SPOTINST_TOKEN), or + from the credentials path. type: str availability_vs_cost: @@ -82,8 +82,7 @@ options: ebs_optimized: description: - - Enable EBS optimization for supported instances which are not enabled by default.; Note - additional charges will - be applied. + - Enable EBS optimization for supported instances which are not enabled by default. Note - additional charges are applied. type: bool ebs_volume_pool: @@ -106,7 +105,7 @@ options: fallback_to_od: description: - - In case of no spots available, Elastigroup will launch an On-demand instance instead. + - In case of no spots available, Elastigroup launches an On-demand instance instead. type: bool health_check_grace_period: @@ -140,15 +139,15 @@ options: id: description: - - The group ID if it already exists and you want to update, or delete it. This will not work unless the uniqueness_by - field is set to ID. When this is set, and the uniqueness_by field is set, the group will either be updated or deleted, + - The group ID if it already exists and you want to update, or delete it. This does not work unless the O(uniqueness_by) + field is set to ID. When this is set, and the O(uniqueness_by) field is set, the group is either updated or deleted, but not created. type: str image_id: description: - - The image ID used to launch the instance.; In case of conflict between Instance type and image type, an error will - be returned. + - The image ID used to launch the instance.; In case of conflict between Instance type and image type, an error is be + returned. required: true type: str @@ -214,13 +213,13 @@ options: on_demand_count: description: - Required if risk is not set. - - Number of on demand instances to launch. All other instances will be spot instances.; Either set this parameter or - the risk parameter. + - Number of on demand instances to launch. All other instances are spot instances.; Either set this parameter or the + O(risk) parameter. type: int on_demand_instance_type: description: - - On-demand instance type that will be provisioned. + - On-demand instance type that is provisioned. type: str opsworks: @@ -278,7 +277,7 @@ options: security_group_ids: description: - One or more security group IDs. - - In case of update it will override the existing Security Group with the new given array. + - In case of update it overrides the existing Security Group with the new given array. required: true type: list elements: str @@ -302,7 +301,7 @@ options: spot_instance_types: description: - - Spot instance type that will be provisioned. + - Spot instance type that is provisioned. required: true type: list elements: str @@ -388,7 +387,7 @@ options: - name description: - If your group names are not unique, you may use this feature to update or delete a specific group. Whenever this property - is set, you must set a group_id in order to update or delete a group, otherwise a group will be created. + is set, you must set a group_id in order to update or delete a group, otherwise a group is created. default: name type: str @@ -399,7 +398,7 @@ options: utilize_reserved_instances: description: - - In case of any available Reserved Instances, Elastigroup will utilize your reservations before purchasing Spot instances. + - In case of any available Reserved Instances, Elastigroup utilizes your reservations before purchasing Spot instances. type: bool wait_for_instances: diff --git a/plugins/modules/ss_3par_cpg.py b/plugins/modules/ss_3par_cpg.py index c9c9b4bd90..0869d67d84 100644 --- a/plugins/modules/ss_3par_cpg.py +++ b/plugins/modules/ss_3par_cpg.py @@ -38,7 +38,7 @@ options: type: str domain: description: - - Specifies the name of the domain in which the object will reside. + - Specifies the name of the domain in which the object resides. type: str growth_increment: description: @@ -46,11 +46,12 @@ options: type: str growth_limit: description: - - Specifies that the autogrow operation is limited to the specified storage amount that sets the growth limit(in MiB, GiB or TiB). + - Specifies that the autogrow operation is limited to the specified storage amount that sets the growth limit (in MiB, + GiB or TiB). type: str growth_warning: description: - - Specifies that the threshold(in MiB, GiB or TiB) of used logical disk space when exceeded results in a warning alert. + - Specifies that the threshold (in MiB, GiB or TiB) of used logical disk space when exceeded results in a warning alert. type: str high_availability: choices: diff --git a/plugins/modules/ssh_config.py b/plugins/modules/ssh_config.py index b4d6ed16bf..39e316993e 100644 --- a/plugins/modules/ssh_config.py +++ b/plugins/modules/ssh_config.py @@ -49,7 +49,7 @@ options: host: description: - The endpoint this configuration is valid for. - - Can be an actual address on the internet or an alias that will connect to the value of O(hostname). + - It can be an actual address on the internet or an alias that connects to the value of O(hostname). required: true type: str hostname: @@ -66,7 +66,7 @@ options: type: str identity_file: description: - - The path to an identity file (SSH private key) that will be used when connecting to this host. + - The path to an identity file (SSH private key) that is used when connecting to this host. - File need to exist and have mode V(0600) to be valid. type: path identities_only: @@ -141,7 +141,7 @@ options: version_added: 10.1.0 other_options: description: - - Provides the option to specify arbitrary SSH config entry options via a dictionary. + - Allows specifying arbitrary SSH config entry options using a dictionary. - The key names must be lower case. Keys with upper case values are rejected. - The values must be strings. Other values are rejected. type: dict @@ -198,22 +198,27 @@ hosts_change_diff: description: A list of host diff changes. returned: on change type: list - sample: [ - { - "example.com": { - "new": { - "hostname": "github.com", - "identityfile": ["/tmp/test_ssh_config/fake_id_rsa"], - "port": "2224" - }, - "old": { - "hostname": "github.com", - "identityfile": ["/tmp/test_ssh_config/fake_id_rsa"], - "port": "2224" + sample: + [ + { + "example.com": { + "new": { + "hostname": "github.com", + "identityfile": [ + "/tmp/test_ssh_config/fake_id_rsa" + ], + "port": "2224" + }, + "old": { + "hostname": "github.com", + "identityfile": [ + "/tmp/test_ssh_config/fake_id_rsa" + ], + "port": "2224" + } } } - } - ] + ] """ import os diff --git a/plugins/modules/stacki_host.py b/plugins/modules/stacki_host.py index bfa4cccff5..095e0b7256 100644 --- a/plugins/modules/stacki_host.py +++ b/plugins/modules/stacki_host.py @@ -119,25 +119,6 @@ EXAMPLES = r""" state: absent """ -RETURN = r""" -changed: - description: Response to whether or not the API call completed successfully. - returned: always - type: bool - sample: true - -stdout: - description: The set of responses from the commands. - returned: always - type: list - sample: ['...', '...'] - -stdout_lines: - description: The value of stdout split into a list. - returned: always - type: list - sample: [['...', '...'], ['...'], ['...']] -""" import json diff --git a/plugins/modules/statusio_maintenance.py b/plugins/modules/statusio_maintenance.py index 9928267bde..31304bb6b7 100644 --- a/plugins/modules/statusio_maintenance.py +++ b/plugins/modules/statusio_maintenance.py @@ -111,7 +111,7 @@ options: minutes: type: int description: - - The length of time in UTC that the maintenance will run (starting from playbook runtime). + - The duration of the maintenance window (starting from playbook runtime). default: 10 start_date: type: str diff --git a/plugins/modules/sudoers.py b/plugins/modules/sudoers.py index ac1ff91ff5..411d87a1c7 100644 --- a/plugins/modules/sudoers.py +++ b/plugins/modules/sudoers.py @@ -42,7 +42,7 @@ options: required: true description: - The name of the sudoers rule. - - This will be used for the filename for the sudoers file managed by this rule. + - This is used for the filename for the sudoers file managed by this rule. type: str noexec: description: @@ -69,12 +69,12 @@ options: version_added: 6.2.0 runas: description: - - Specify the target user the command(s) will run as. + - Specify the target user the command(s) runs as. type: str version_added: 4.7.0 sudoers_path: description: - - The path which sudoers config files will be managed in. + - The path which sudoers config files are managed in. default: /etc/sudoers.d type: str state: @@ -92,9 +92,9 @@ options: type: str validation: description: - - If V(absent), the sudoers rule will be added without validation. - - If V(detect) and visudo is available, then the sudoers rule will be validated by visudo. - - If V(required), visudo must be available to validate the sudoers rule. + - If V(absent), the sudoers rule is added without validation. + - If V(detect) and C(visudo) is available, then the sudoers rule is validated by C(visudo). + - If V(required), C(visudo) must be available to validate the sudoers rule. type: str default: detect choices: [absent, detect, required] diff --git a/plugins/modules/supervisorctl.py b/plugins/modules/supervisorctl.py index 7df1674fea..c2ceb1a52b 100644 --- a/plugins/modules/supervisorctl.py +++ b/plugins/modules/supervisorctl.py @@ -26,8 +26,8 @@ options: type: str description: - The name of the supervisord program or group to manage. - - The name will be taken as group name when it ends with a colon V(:). - - If O(name=all), all programs and program groups will be managed. + - The name is taken as group name when it ends with a colon V(:). + - If O(name=all), all programs and program groups are managed. required: true config: type: path @@ -67,12 +67,11 @@ options: description: - Path to C(supervisorctl) executable. notes: - - When O(state=present), the module will call C(supervisorctl reread) then C(supervisorctl add) if the program/group does - not exist. - - When O(state=restarted), the module will call C(supervisorctl update) then call C(supervisorctl restart). - - When O(state=absent), the module will call C(supervisorctl reread) then C(supervisorctl remove) to remove the target program/group. - If the program/group is still running, the action will fail. If you want to stop the program/group before removing, use - O(stop_before_removing=true). + - When O(state=present), the module calls C(supervisorctl reread) then C(supervisorctl add) if the program/group does not + exist. + - When O(state=restarted), the module calls C(supervisorctl update) then calls C(supervisorctl restart). + - When O(state=absent), the module calls C(supervisorctl reread) then C(supervisorctl remove) to remove the target program/group. + If the program/group is still running, the action fails. If you want to stop the program/group before removing, use O(stop_before_removing=true). requirements: ["supervisorctl"] author: - "Matt Wright (@mattupstate)" diff --git a/plugins/modules/svc.py b/plugins/modules/svc.py index 42b6bcbeb9..4a6e21ef5f 100644 --- a/plugins/modules/svc.py +++ b/plugins/modules/svc.py @@ -30,10 +30,10 @@ options: required: true state: description: - - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary. - - V(restarted) will always bounce the svc (svc -t) and V(killed) will always bounce the svc (svc -k). - - V(reloaded) will send a sigusr1 (svc -1). - - V(once) will run a normally downed svc once (svc -o), not really an idempotent operation. + - V(started)/V(stopped) are idempotent actions that do not run commands unless necessary. + - V(restarted) always bounces the svc (svc -t) and V(killed) always bounces the svc (svc -k). + - V(reloaded) sends a sigusr1 (svc -1). + - V(once) runs a normally downed svc once (svc -o), not really an idempotent operation. type: str choices: [killed, once, reloaded, restarted, started, stopped] downed: diff --git a/plugins/modules/svr4pkg.py b/plugins/modules/svr4pkg.py index 34aa599e01..a939801603 100644 --- a/plugins/modules/svr4pkg.py +++ b/plugins/modules/svr4pkg.py @@ -16,7 +16,7 @@ short_description: Manage Solaris SVR4 packages description: - Manages SVR4 packages on Solaris 10 and 11. - These were the native packages on Solaris <= 10 and are available as a legacy feature in Solaris 11. - - Note that this is a very basic packaging system. It will not enforce dependencies on install or remove. + - Note that this is a very basic packaging system. It does not enforce dependencies on install or remove. author: "Boyd Adamson (@brontitall)" extends_documentation_fragment: - community.general.attributes diff --git a/plugins/modules/swdepot.py b/plugins/modules/swdepot.py index 628c63f810..5ac730f36f 100644 --- a/plugins/modules/swdepot.py +++ b/plugins/modules/swdepot.py @@ -16,7 +16,7 @@ DOCUMENTATION = r""" module: swdepot short_description: Manage packages with swdepot package manager (HP-UX) description: - - Will install, upgrade and remove packages with swdepot package manager (HP-UX). + - Installs, upgrades, and removes packages with C(swdepot) package manager (HP-UX). notes: [] author: "Raul Melo (@melodous)" extends_documentation_fragment: diff --git a/plugins/modules/systemd_info.py b/plugins/modules/systemd_info.py index 139365856d..12f308849c 100644 --- a/plugins/modules/systemd_info.py +++ b/plugins/modules/systemd_info.py @@ -14,13 +14,13 @@ short_description: Gather C(systemd) unit info description: - This module gathers info about systemd units (services, targets, sockets, mounts, timers). - Timer units are supported since community.general 10.5.0. - - It runs C(systemctl list-units) (or processes selected units) and collects properties - for each unit using C(systemctl show). - - In case a unit has multiple properties with the same name, only the value of the first one will be collected. - - Even if a unit has a RV(units.loadstate) of V(not-found) or V(masked), it is returned, - but only with the minimal properties (RV(units.name), RV(units.loadstate), RV(units.activestate), RV(units.substate)). - - When O(unitname) and O(extra_properties) are used, the module first checks if the unit exists, - then check if properties exist. If not, the module fails. + - It runs C(systemctl list-units) (or processes selected units) and collects properties for each unit using C(systemctl + show). + - In case a unit has multiple properties with the same name, only the value of the first one is collected. + - Even if a unit has a RV(units.loadstate) of V(not-found) or V(masked), it is returned, but only with the minimal properties + (RV(units.name), RV(units.loadstate), RV(units.activestate), RV(units.substate)). + - When O(unitname) and O(extra_properties) are used, the module first checks if the unit exists, then check if properties + exist. If not, the module fails. - When O(unitname) is used with wildcard expressions, the module checks for units that match the indicated expressions, if units are not present for all the indicated expressions, the module fails. version_added: "10.4.0" @@ -89,7 +89,7 @@ RETURN = r""" units: description: - Dictionary of systemd unit info keyed by unit name. - - Additional fields will be returned depending on the value of O(extra_properties). + - Additional fields are returned depending on the value of O(extra_properties). returned: success type: dict elements: dict @@ -116,7 +116,8 @@ units: substate: description: - The detailed sub state of the unit. - - The most common values are V(running), V(dead), V(exited), V(failed), V(listening), V(active), and V(mounted), but other values are possible as well. + - The most common values are V(running), V(dead), V(exited), V(failed), V(listening), V(active), and V(mounted), but + other values are possible as well. returned: always type: str sample: running diff --git a/plugins/modules/sysupgrade.py b/plugins/modules/sysupgrade.py index 64c3b61ac8..4f1d2535a5 100644 --- a/plugins/modules/sysupgrade.py +++ b/plugins/modules/sysupgrade.py @@ -25,7 +25,7 @@ options: snapshot: description: - Apply the latest snapshot. - - Otherwise release will be applied. + - Otherwise release is applied. default: false type: bool force: @@ -36,14 +36,13 @@ options: keep_files: description: - Keep the files under C(/home/_sysupgrade). - - By default, the files will be deleted after the upgrade. + - By default, the files are deleted after the upgrade. default: false type: bool fetch_only: description: - Fetch and verify files and create C(/bsd.upgrade) but do not reboot. - - Set to V(false) if you want C(sysupgrade) to reboot. This will cause Ansible to error, as it expects the module to - exit gracefully. See the examples. + - Set to V(false) if you want C(sysupgrade) to reboot. This causes the module to fail. See the examples. default: true type: bool installurl: