[PR #9352/9fc3092b backport][stable-9] s[e-n]*: normalize docs (#9398)

s[e-n]*: normalize docs (#9352)

* s[e-n]*: normalize docs

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

* quote line with : and remove extraneous notes

* Update plugins/modules/slack.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update plugins/modules/seport.py

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit 9fc3092bb3)

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

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 file type that should have SELinux contexts applied.
-    - "The following file type options are available:"
+      - 'The following file type options are available:'
-    - V(a) for all files,
+      - V(a) for all files,
-    - V(b) for block devices,
+      - V(b) for block devices,
-    - V(c) for character devices,
+      - V(c) for character devices,
-    - V(d) for directories,
+      - V(d) for directories,
-    - V(f) for regular files,
+      - V(f) for regular files,
-    - V(l) for symbolic links,
+      - V(l) for symbolic links,
-    - V(p) for named pipes,
+      - V(p) for named pipes,
-    - V(s) for socket files.
+      - 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.
+      - Path to use to substitute file context(s) for the specified O(target). The context labeling for the O(target) subtree is made equivalent
-    - This is also referred to as SELinux file context equivalence and it implements the C(equal) functionality of the SELinux management tools.
+        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).
+      - SELinux user for the specified O(target).
-    - Defaults to V(system_u) for new file contexts and to existing value when modifying file contexts.
+      - 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).
+      - SELinux range for the specified O(target).
-    - Defaults to V(s0) for new file contexts and to existing value when modifying file contexts.
+      - 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).
+      - 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).
+      - 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.
+      - Reload SELinux policy after commit.
-    - Note that this does not apply SELinux file contexts to existing files.
+      - 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.
+  - The changes are persistent across reboots.
-- O(setype) and O(substitute) are mutually exclusive.
+  - O(setype) and O(substitute) are mutually exclusive.
-- If O(state=present) then one of O(setype) or O(substitute) is mandatory.
+  - 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
+  - The M(community.general.sefcontext) module does not modify existing files to the new SELinux context(s), so it is advisable to first create
-  SELinux context(s), so it is advisable to first create the SELinux
+    the SELinux file contexts before creating files, or run C(restorecon) manually for the existing files that require the new SELinux file contexts.
-  file contexts before creating files, or run C(restorecon) manually
+  - Not applying SELinux fcontexts to existing files is a deliberate decision as it would be unclear what reported changes would entail to, and
-  for the existing files that require the new SELinux file contexts.
+    there is no guarantee that applying SELinux fcontext does not pick up other unrelated prior changes.
-- 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.
 requirements:
-- libselinux-python
+  - libselinux-python
-- policycoreutils-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
 

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.
+      - 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.
+      - 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."
+      - 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).
+  - Requires a recent version of SELinux and C(policycoreutils-python) (EL 6 or newer).
-requirements: [ policycoreutils-python ]
+requirements: [policycoreutils-python]
 author:
-- Michael Scherer (@mscherer) <misc@zarb.org>
+  - Michael Scherer (@mscherer) <misc@zarb.org>
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Change the httpd_t domain to permissive
   community.general.selinux_permissive:
     name: httpd_t
     permissive: true
-'''
+"""
 
 import traceback
 

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
+  - The changes are persistent across reboots.
-   - Not tested on any debian based system
+  - Not tested on any debian based system.
-requirements: [ 'libselinux', 'policycoreutils' ]
+requirements: ['libselinux', 'policycoreutils']
 author:
-- Dan Keder (@dankeder)
+  - Dan Keder (@dankeder)
-- Petr Lautrbach (@bachradsusi)
+  - Petr Lautrbach (@bachradsusi)
-- James Cassell (@jamescassell)
+  - 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

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
+  - Sends an email with a SendGrid account through their API, not through the SMTP service.
-    the SMTP service."
 notes:
-  - "This module is non-idempotent because it sends an email through the
+  - 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.
-    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
+  - 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).
-    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"
 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 }}"
+    username: "{{ sendgrid_username }}"
-      password: "{{ sendgrid_password }}"
+    password: "{{ sendgrid_password }}"
-      from_address: "build@mycompany.com"
+    from_address: "build@mycompany.com"
-      to_addresses:
+    to_addresses:
-        - "ops@mycompany.com"
+      - "ops@mycompany.com"
-        - "devteam@mycompany.com"
+      - "devteam@mycompany.com"
-      subject: "Build failure!."
+    subject: "Build failure!."
-      body: "Unable to pull source repository from Git server."
+    body: "Unable to pull source repository from Git server."
   delegate_to: localhost
-'''
+"""
 
 # =======================================
 # sendgrid module support methods

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
+      - The name of the check.
-      - This is the key that is used to determine whether a check exists
+      - 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
+      - Whether the check should be present or not.
-    choices: [ 'present', 'absent' ]
+    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
+      - List of subscribers/channels this check should run for.
-      - See sensu_subscribers to subscribe a machine to a channel
+      - 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
+      - Whether the check should be scheduled by the sensu client or server.
-      - This option obviates the need for specifying the O(subscribers) option
+      - 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

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
+      - Whether the client should be present or not.
-    choices: [ 'present', 'absent' ]
+    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

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
+      - Whether the handler should be present or not.
-    choices: [ 'present', 'absent' ]
+    choices: ['present', 'absent']
     default: present
   name:
     type: str
@@ -38,8 +37,8 @@ options:
   type:
     type: str
     description:
-      - The handler type
+      - The handler type.
-    choices: [ 'pipe', 'tcp', 'udp', 'transport', 'set' ]
+    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").'
+      - 'NOTE: the handlers attribute is only required for handler sets (that is, handlers configured with O(type=set)).'
-notes:
+"""
-  - Check mode is supported
-'''
 
-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

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
+  - Create and clear (delete) a silence entries via the Sensu API for subscriptions and checks.
-    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
+      - If specified, the silence entry will be automatically cleared after this number of seconds.
-        after this number of seconds.
   expire_on_resolve:
     description:
-      - If specified as true, the silence entry will be automatically
+      - If specified as true, the silence entry will be automatically cleared once the condition it is silencing is resolved.
-        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
+      - If specified, this free-form string is used to provide context or rationale for the reason this silence entry was created.
-        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.
+      - To create a silence entry for a client prepend C(client:) to client name. Example - C(client:server1.example.dev).
-        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
 

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
+      - Whether the machine should subscribe or unsubscribe from the channel.
-    choices: [ 'present', 'absent' ]
+    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
+  description: The reasons why the module changed or did not change something.
-    returned: success
+  returned: success
-    type: list
+  type: list
-    sample: ["channel subscription was absent and state is `present'"]
+  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

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.
+  - The changes are persistent across reboots.
-   - Not tested on any debian based system.
+  - Not tested on any Debian based system.
 requirements:
-- libselinux-python
+  - libselinux-python
-- policycoreutils-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
 

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.
+  - Currently, the C(serverless) command must be in the path of the node executing the task. In the future this may be a flag.
-     In the future this may be a flag.
 requirements:
-- serverless
+  - serverless
-- yaml
+  - 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
 

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)
+  - 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
-    to specify locations to search if the default paths do not work.
+    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 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
-    the module will attempt to shutdown the system by calling C(systemctl shutdown).
+    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)
+  - Matt Davis (@nitzmahone)
-    - Sam Doran (@samdoran)
+  - Sam Doran (@samdoran)
-    - Amin Vakil (@aminvakil)
+  - 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
-'''
+"""

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
+      - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary. V(restarted) will always bounce the service.
-        commands unless necessary.  V(restarted) will always bounce the
+        V(reloaded) will always reload.
-        service.  V(reloaded) will always reload.
       - At least one of O(state) and O(enabled) are required.
-      - Note that V(reloaded) will start the
+      - Note that V(reloaded) will start the service if it is not already started, even if your chosen init system would not normally.
-        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

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
+    - name: Build instance request
-    community.general.sl_vm:
+      community.general.sl_vm:
-      hostname: instance-1
+        hostname: instance-1
-      domain: anydomain.com
+        domain: anydomain.com
-      datacenter: dal09
+        datacenter: dal09
-      tags: ansible-module-test
+        tags: ansible-module-test
-      hourly: true
+        hourly: true
-      private: false
+        private: false
-      dedicated: false
+        dedicated: false
-      local_disk: true
+        local_disk: true
-      cpus: 1
+        cpus: 1
-      memory: 1024
+        memory: 1024
-      disks: [25]
+        disks: [25]
-      os_code: UBUNTU_LATEST
+        os_code: UBUNTU_LATEST
-      wait: false
+        wait: false
 
 - name: Build additional instances
   hosts: localhost
   gather_facts: false
   tasks:
-  - name: Build instances request
+    - name: Build instances request
-    community.general.sl_vm:
+      community.general.sl_vm:
-      hostname: "{{ item.hostname }}"
+        hostname: "{{ item.hostname }}"
-      domain: "{{ item.domain }}"
+        domain: "{{ item.domain }}"
-      datacenter: "{{ item.datacenter }}"
+        datacenter: "{{ item.datacenter }}"
-      tags: "{{ item.tags }}"
+        tags: "{{ item.tags }}"
-      hourly: "{{ item.hourly }}"
+        hourly: "{{ item.hourly }}"
-      private: "{{ item.private }}"
+        private: "{{ item.private }}"
-      dedicated: "{{ item.dedicated }}"
+        dedicated: "{{ item.dedicated }}"
-      local_disk: "{{ item.local_disk }}"
+        local_disk: "{{ item.local_disk }}"
-      cpus: "{{ item.cpus }}"
+        cpus: "{{ item.cpus }}"
-      memory: "{{ item.memory }}"
+        memory: "{{ item.memory }}"
-      disks: "{{ item.disks }}"
+        disks: "{{ item.disks }}"
-      os_code: "{{ item.os_code }}"
+        os_code: "{{ item.os_code }}"
-      ssh_keys: "{{ item.ssh_keys }}"
+        ssh_keys: "{{ item.ssh_keys }}"
-      wait: "{{ item.wait }}"
+        wait: "{{ item.wait }}"
-    with_items:
+      with_items:
-      - hostname: instance-2
+        - hostname: instance-2
-        domain: anydomain.com
+          domain: anydomain.com
-        datacenter: dal09
+          datacenter: dal09
-        tags:
+          tags:
-          - ansible-module-test
+            - ansible-module-test
-          - ansible-module-test-replicas
+            - ansible-module-test-replicas
-        hourly: true
+          hourly: true
-        private: false
+          private: false
-        dedicated: false
+          dedicated: false
-        local_disk: true
+          local_disk: true
-        cpus: 1
+          cpus: 1
-        memory: 1024
+          memory: 1024
-        disks:
+          disks:
-          - 25
+            - 25
-          - 100
+            - 100
-        os_code: UBUNTU_LATEST
+          os_code: UBUNTU_LATEST
-        ssh_keys: []
+          ssh_keys: []
-        wait: true
+          wait: true
-      - hostname: instance-3
+        - hostname: instance-3
-        domain: anydomain.com
+          domain: anydomain.com
-        datacenter: dal09
+          datacenter: dal09
-        tags:
+          tags:
-          - ansible-module-test
+            - ansible-module-test
-          - ansible-module-test-replicas
+            - ansible-module-test-replicas
-        hourly: true
+          hourly: true
-        private: false
+          private: false
-        dedicated: false
+          dedicated: false
-        local_disk: true
+          local_disk: true
-        cpus: 1
+          cpus: 1
-        memory: 1024
+          memory: 1024
-        disks:
+          disks:
-          - 25
+            - 25
-          - 100
+            - 100
-        os_code: UBUNTU_LATEST
+          os_code: UBUNTU_LATEST
-        ssh_keys: []
+          ssh_keys: []
-        wait: true
+          wait: true
 
 - name: Cancel instances
   hosts: localhost
   gather_facts: false
   tasks:
-  - name: Cancel by tag
+    - name: Cancel by tag
-    community.general.sl_vm:
+      community.general.sl_vm:
-      state: absent
+        state: absent
-      tags: ansible-module-test
+        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

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
+      - Slack (sub)domain for your environment without protocol. (For example V(example.slack.com).) In Ansible 1.8 and beyond, this is deprecated
-        V(example.slack.com).) In Ansible 1.8 and beyond, this is deprecated and may
+        and may be ignored. See token documentation for information.
-        be ignored.  See token documentation for information.
   token:
     type: str
     description:
-      - Slack integration token. This authenticates you to the slack service.
+      - Slack integration token. This authenticates you to the slack service. Make sure to use the correct type of token, depending on what method
-        Make sure to use the correct type of token, depending on what method you use.
+        you use.
-      - "Webhook token:
+      - 'Webhook token: Prior to Ansible 1.8, a token looked like V(3Ffe373sfhRE6y42Fg3rvf4GlK). In Ansible 1.8 and above, Ansible adapts to the
-        Prior to Ansible 1.8, a token looked like V(3Ffe373sfhRE6y42Fg3rvf4GlK).  In
+        new slack API where tokens look like V(G922VJP24/D921DW937/3Ffe373sfhRE6y42Fg3rvf4GlK). If tokens are in the new format then slack will
-        Ansible 1.8 and above, Ansible adapts to the new slack API where tokens look
+        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
-        like V(G922VJP24/D921DW937/3Ffe373sfhRE6y42Fg3rvf4GlK).  If tokens
+        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
-        are in the new format then slack will ignore any value of domain.  If
+        the webhook tokens. In slack these are found in the webhook URL which are obtained under the apps and integrations. The incoming webhooks
-        the token is in the old format the domain is required.  Ansible has no
+        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
-        control of when slack will get rid of the old API.  When slack does
+        webhooks can be added. The key is on the end of the URL given to you in that section.'
-        that the old format will stop working.  ** Please keep in mind the tokens
+      - "WebAPI token: Slack WebAPI requires a personal, bot or work application token. These tokens start with V(xoxp-), V(xoxb-) or V(xoxa-),
-        are not the API tokens but are the webhook tokens.  In slack these are
+        for example V(xoxb-1234-56789abcdefghijklmnop). WebAPI token is required if you intend to receive thread_id. See Slack's documentation
-        found in the webhook URL which are obtained under the apps and integrations.
+        (U(https://api.slack.com/docs/token-types)) for more information."
-        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.
+      - Message to send. Note that the module does not handle escaping characters. Plain-text angle brackets and ampersands should be converted
-        Plain-text angle brackets and ampersands should be converted to HTML entities (e.g. & to &) before sending.
+        to HTML entities (for example C(&) to C(&)) before sending. See Slack's documentation (U(https://api.slack.com/docs/message-formatting)) for more.
-        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
+      - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.
-        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).
+      - 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
-        These prefixes only cover a small set of the prefixes that should not have a V(#) prepended.
+        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
-        Since an exact condition which O(channel) values must not have the V(#) prefix is not known,
+        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)
-        the value V(auto) for this option will be deprecated in the future. It is best to explicitly set
+        or O(prepend_hash=never) to obtain the needed behavior.
-        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
+          - type: mrkdwn
-          text: |-
+            text: |-
-            *System A*
+              *System A*
-            load average: 0,74, 0,66, 0,63
+              load average: 0,74, 0,66, 0,63
-        - type: mrkdwn
+          - type: mrkdwn
-          text: |-
+            text: |-
-            *System B*
+              *System B*
-            load average: 5,16, 4,64, 2,43
+              load average: 5,16, 4,64, 2,43
 
 - name: Send a message with a link using Slack markup
   community.general.slack:

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
+  - Manage binary packages for Slackware using C(slackpkg) which is available in versions after 12.2.
-      is available in versions after 12.2.
 extends_documentation_fragment:
-    - community.general.attributes
+  - community.general.attributes
 attributes:
-    check_mode:
+  check_mode:
-        support: full
+    support: full
-    diff_mode:
+  diff_mode:
-        support: none
+    support: none
 options:
-    name:
+  name:
-        description:
+    description:
-            - name of package to install/remove
+      - Name of package to install/remove.
-        required: true
+    required: true
-        type: list
+    type: list
-        elements: str
+    elements: str
-        aliases: [pkg]
+    aliases: [pkg]
 
-    state:
+  state:
-        description:
+    description:
-            - State of the package, you can use V(installed) as an alias for V(present) and V(removed) as one for V(absent).
+      - 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' ]
+    choices: ['present', 'absent', 'latest', 'installed', 'removed']
-        required: false
+    required: false
-        default: present
+    default: present
-        type: str
+    type: str
 
-    update_cache:
+  update_cache:
-        description:
+    description:
-            - update the package database first
+      - Update the package database first.
-        required: false
+    required: false
-        default: false
+    default: false
-        type: bool
+    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
 

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
-    - community.general.attributes.info_module
+  - community.general.attributes.info_module
 attributes:
-    check_mode:
+  check_mode:
-        version_added: 3.3.0
+    version_added: 3.3.0
-        # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
+    # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
 options:
-    filters:
+  filters:
-        description:
+    description:
-            - Criteria for selecting image. Can be any value from image
+      - Criteria for selecting image. Can be any value from image manifest and V(published_date), V(published), V(source), V(clones), and V(size).
-              manifest and C(published_date), C(published), C(source), C(clones),
+      - More information can be found at U(https://smartos.org/man/1m/imgadm) under C(imgadm list).
-              and C(size). More information can be found at U(https://smartos.org/man/1m/imgadm)
+    type: str
-              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'] }}
+    msg: "{{ result.smartos_images[item]['name'] }}-{{ result.smartos_images[item]['version'] }} has {{ result.smartos_images[item]['clones'] }} VM(s)"
-         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'] }}
+    msg: "{{ smartos_images[item]['name'] }}-{{ smartos_images[item]['version'] }} has {{ smartos_images[item]['clones'] }} VM(s)"
-         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

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:
+  check_mode:
-        support: full
+    support: full
-    diff_mode:
+  diff_mode:
-        support: none
+    support: none
 options:
-    name:
+  name:
-        description:
+    description:
-            - Name of the snaps to be installed.
+      - Name of the snaps to be installed.
-            - Any named snap accepted by the C(snap) command is valid.
+      - 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.
-              O(dangerous=true) may be necessary when installing `.snap` files. See O(dangerous) for more details.
+    required: true
-        required: true
+    type: list
-        type: list
+    elements: str
-        elements: str
+  state:
-    state:
+    description:
-        description:
+      - Desired state of the package.
-            - 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 will use C(snap install) if the snap is not installed,
+    default: present
-              and C(snap refresh) if it is installed but from a different channel.
+    choices: [absent, present, enabled, disabled]
-        default: present
+    type: str
-        choices: [ absent, present, enabled, disabled ]
+  classic:
-        type: str
+    description:
-    classic:
+      - Install a snap that has classic confinement.
-        description:
+      - This option corresponds to the C(--classic) argument of the C(snap install) command.
-            - Install a snap that has classic confinement.
+      - This level of confinement is permissive, granting full system access, similar to that of traditionally packaged applications that do not
-            - This option corresponds to the C(--classic) argument of the C(snap install) command.
+        use sandboxing mechanisms. This option can only be specified when the task involves a single snap.
-            - This level of confinement is permissive, granting full system access,
+      - See U(https://snapcraft.io/docs/snap-confinement) for more details about classic confinement and confinement levels.
-              similar to that of traditionally packaged applications that do not use sandboxing mechanisms.
+    type: bool
-              This option can only be specified when the task involves a single snap.
+    required: false
-            - See U(https://snapcraft.io/docs/snap-confinement) for more details about classic confinement and confinement levels.
+    default: false
-
+  channel:
-        type: bool
+    description:
-        required: false
+      - 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
-        default: false
+        task.
-    channel:
+      - If not passed, the C(snap) command will default to V(stable).
-        description:
+      - 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
-            - Define which release of a snap is installed and tracked for updates.
+        the channel to be V(latest/edge).
-              This option can only be specified if there is a single snap in the task.
+      - See U(https://snapcraft.io/docs/channels) for more details about snap channels.
-            - If not passed, the C(snap) command will default to V(stable).
+    type: str
-            - If the value passed does not contain the C(track), it will default to C(latest).
+    required: false
-              For example, if V(edge) is passed, the module will assume the channel to be V(latest/edge).
+  options:
-            - See U(https://snapcraft.io/docs/channels) for more details about snap channels.
+    description:
-        type: str
+      - 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
-        required: false
+        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:
+      - Options will only be applied when C(state) is set to V(present). This is done after the necessary installation or refresh (upgrade/downgrade)
-        description:
+        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 will be applied
+      - See U(https://snapcraft.io/docs/configuration-in-snaps) for more details about snap configuration options.
-              to that snap only. If the snap name is omitted, the options will be applied to all snaps listed in O(name). Options will
+    required: false
-              only be applied to active snaps.
+    type: list
-            - Options will only be applied when C(state) is set to V(present).
+    elements: str
-              This is done after the necessary installation
+    version_added: 4.4.0
-              or refresh (upgrade/downgrade) of all the snaps listed in O(name).
+  dangerous:
-            - See U(https://snapcraft.io/docs/configuration-in-snaps) for more details about snap configuration options.
+    description:
-
+      - Install the snap in dangerous mode, without validating its assertions and signatures.
-        required: false
+      - This is useful when installing local snaps that are either unsigned or have signatures that have not been acknowledged.
-        type: list
+      - See U(https://snapcraft.io/docs/install-modes) for more details about installation modes.
-        elements: str
+    type: bool
-        version_added: 4.4.0
+    required: false
-    dangerous:
+    default: false
-        description:
+    version_added: 7.2.0
-            - 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.
+  - Privileged operations, such as installing and configuring snaps, require root priviledges. This is only the case if the user has not logged
-    This is only the case if the user has not logged in to the Snap Store.
+    in to the Snap Store.
-
 author:
-    - Victor Carceler (@vcarceler) <vcarceler@iespuigcastellar.xeill.net>
+  - Victor Carceler (@vcarceler) <vcarceler@iespuigcastellar.xeill.net>
-    - Stanislas Lange (@angristan) <angristan@pm.me>
+  - Stanislas Lange (@angristan) <angristan@pm.me>
 
 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
+  description: Whether or not the snaps were installed with the classic confinement.
-    type: bool
+  type: bool
-    returned: When snaps are installed
+  returned: When snaps are installed
 channel:
-    description: The channel the snaps were installed from
+  description: The channel the snaps were installed from.
-    type: str
+  type: str
-    returned: When snaps are installed
+  returned: When snaps are installed
 cmd:
-    description: The command that was executed on the host
+  description: The command that was executed on the host.
-    type: str
+  type: str
-    returned: When changed is true
+  returned: When changed is true
 snaps_installed:
-    description: The list of actually installed snaps
+  description: The list of actually installed snaps.
-    type: list
+  type: list
-    returned: When any snaps have been installed
+  returned: When any snaps have been installed
 snaps_removed:
-    description: The list of actually removed snaps
+  description: The list of actually removed snaps.
-    type: list
+  type: list
-    returned: When any snaps have been removed
+  returned: When any snaps have been removed
 options_changed:
-    description: The list of options set/changed in format C(snap:key=value).
+  description: The list of options set/changed in format C(snap:key=value).
-    type: list
+  type: list
-    returned: When any options have been changed/set
+  returned: When any options have been changed/set
-    version_added: 4.4.0
+  version_added: 4.4.0
-'''
+"""
 
 import re
 import json

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:
+  check_mode:
-        support: full
+    support: full
-    diff_mode:
+  diff_mode:
-        support: full
+    support: full
 options:
-    state:
+  state:
-        description:
+    description:
-            - Desired state of the alias.
+      - Desired state of the alias.
-        type: str
+    type: str
-        choices: [ absent, present ]
+    choices: [absent, present]
-        default: present
+    default: present
-    name:
+  name:
-        description:
+    description:
-            - Name of the snap.
+      - Name of the snap.
-        type: str
+    type: str
-    alias:
+  alias:
-        description:
+    description:
-            - Aliases to be created or removed.
+      - Aliases to be created or removed.
-        type: list
+    type: list
-        elements: str
+    elements: str
-        aliases: [aliases]
+    aliases: [aliases]
 
 author:
-    - Alexei Znamensky (@russoz) <russoz@gmail.com>
+  - Alexei Znamensky (@russoz) <russoz@gmail.com>
 
 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.
+  description: The snap aliases after execution. If called in check mode, then the list represents the state before execution.
-    type: list
+  type: list
-    elements: str
+  elements: str
-    returned: always
+  returned: always
-'''
+"""
 
 
 import re

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
+  - Retrieve facts for a device using SNMP, the facts will be inserted to the C(ansible_facts) key.
-      inserted to the ansible_facts key.
 requirements:
-    - pysnmp
+  - pysnmp
 extends_documentation_fragment:
-    - community.general.attributes
+  - community.general.attributes
-    - community.general.attributes.facts
+  - community.general.attributes.facts
-    - community.general.attributes.facts_module
+  - community.general.attributes.facts_module
 attributes:
-    check_mode:
+  check_mode:
-        version_added: 3.3.0
+    version_added: 3.3.0
-        # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
+    # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
 options:
-    host:
+  host:
-        description:
+    description:
-            - Set to target SNMP server (normally C({{ inventory_hostname }})).
+      - Set to target SNMP server (normally C({{ inventory_hostname }})).
-        type: str
+    type: str
-        required: true
+    required: true
-    version:
+  version:
-        description:
+    description:
-            - SNMP Version to use, V(v2), V(v2c) or V(v3).
+      - SNMP Version to use, V(v2), V(v2c) or V(v3).
-        type: str
+    type: str
-        required: true
+    required: true
-        choices: [ v2, v2c, v3 ]
+    choices: [v2, v2c, v3]
-    community:
+  community:
-        description:
+    description:
-            - The SNMP community string, required if O(version) is V(v2) or V(v2c).
+      - The SNMP community string, required if O(version) is V(v2) or V(v2c).
-        type: str
+    type: str
-    level:
+  level:
-        description:
+    description:
-            - Authentication level.
+      - Authentication level.
-            - Required if O(version=v3).
+      - Required if O(version=v3).
-        type: str
+    type: str
-        choices: [ authNoPriv, authPriv ]
+    choices: [authNoPriv, authPriv]
-    username:
+  username:
-        description:
+    description:
-            - Username for SNMPv3.
+      - Username for SNMPv3.
-            - Required if O(version=v3).
+      - Required if O(version=v3).
-        type: str
+    type: str
-    integrity:
+  integrity:
-        description:
+    description:
-            - Hashing algorithm.
+      - Hashing algorithm.
-            - Required if O(version=v3).
+      - Required if O(version=v3).
-        type: str
+    type: str
-        choices: [ md5, sha ]
+    choices: [md5, sha]
-    authkey:
+  authkey:
-        description:
+    description:
-            - Authentication key.
+      - Authentication key.
-            - Required O(version=v3).
+      - Required O(version=v3).
-        type: str
+    type: str
-    privacy:
+  privacy:
-        description:
+    description:
-            - Encryption algorithm.
+      - Encryption algorithm.
-            - Required if O(level=authPriv).
+      - Required if O(level=authPriv).
-        type: str
+    type: str
-        choices: [ aes, des ]
+    choices: [aes, des]
-    privkey:
+  privkey:
-        description:
+    description:
-            - Encryption key.
+      - Encryption key.
-            - Required if O(level=authPriv).
+      - Required if O(level=authPriv).
-        type: str
+    type: str
-    timeout:
+  timeout:
-        description:
+    description:
-            - Response timeout in seconds.
+      - Response timeout in seconds.
-        type: int
+    type: int
-        version_added: 2.3.0
+    version_added: 2.3.0
-    retries:
+  retries:
-        description:
+    description:
-            - Maximum number of request retries, 0 retries means just a single request.
+      - Maximum number of request retries, 0 retries means just a single request.
-        type: int
+    type: int
-        version_added: 2.3.0
+    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",
+      "adminstatus": "up",
-        "description": "",
+      "description": "",
-        "ifindex": "1",
+      "ifindex": "1",
-        "ipv4": [
+      "ipv4": [
-            {
+        {
-                "address": "127.0.0.1",
+          "address": "127.0.0.1",
-                "netmask": "255.0.0.0"
+          "netmask": "255.0.0.0"
-            }
+        }
-        ],
+      ],
-        "mac": "",
+      "mac": "",
-        "mtu": "65536",
+      "mtu": "65536",
-        "name": "lo",
+      "name": "lo",
-        "operstatus": "up",
+      "operstatus": "up",
-        "speed": "65536"
+      "speed": "65536"
     },
     "2": {
-        "adminstatus": "up",
+      "adminstatus": "up",
-        "description": "",
+      "description": "",
-        "ifindex": "2",
+      "ifindex": "2",
-        "ipv4": [
+      "ipv4": [
-            {
+        {
-                "address": "192.168.213.128",
+          "address": "192.168.213.128",
-                "netmask": "255.255.255.0"
+          "netmask": "255.255.255.0"
-            }
+        }
-        ],
+      ],
-        "mac": "000a305a52a1",
+      "mac": "000a305a52a1",
-        "mtu": "1500",
+      "mtu": "1500",
-        "name": "Intel Corporation 82545EM Gigabit Ethernet Controller (Copper)",
+      "name": "Intel Corporation 82545EM Gigabit Ethernet Controller (Copper)",
-        "operstatus": "up",
+      "operstatus": "up",
-        "speed": "1500"
+      "speed": "1500"
     }
   }
-'''
+"""
 
 import binascii
 from collections import defaultdict