[PR #9435/2f82bd8e backport][stable-10] Adjust doc style (#9445)

Adjust doc style (#9435)

* adjust doc style

* Update plugins/modules/swupd.py

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

* restore sanity

---------

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

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

plugins/modules/sensu_check.py

@@ -40,7 +40,7 @@ options:
   path:
     type: str
     description:
-      - Path to the json file of the check to be added/removed.
+      - 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.
     default: /etc/sensu/conf.d/checks.json
@@ -110,7 +110,7 @@ options:
   publish:
     description:
       - Whether the check should be scheduled at all.
-      - You can still issue it via the sensu API.
+      - You can still issue it using the sensu API.
       - Default is V(false).
     type: bool
   occurrences:
@@ -125,7 +125,7 @@ options:
   aggregate:
     description:
       - Classifies the check as an aggregate check,
-        making it available via the aggregate API.
+        making it available using the aggregate API.
       - Default is V(false).
     type: bool
   low_flap_threshold:
@@ -140,11 +140,11 @@ options:
     type: dict
     description:
       - A hash/dictionary of custom parameters for mixing to the configuration.
-      - You can't rewrite others module parameters using this.
+      - You cannot rewrite other 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).
+      - The check source, used to create a JIT Sensu client for an external resource (for example a network switch).
 author: "Anders Ingemann (@andsens)"
 """
 

plugins/modules/sensu_client.py

@@ -43,7 +43,7 @@ options:
     type: list
     elements: str
     description:
-      - An array of client subscriptions, a list of roles and/or responsibilities assigned to the system (e.g. webserver).
+      - An array of client subscriptions, a list of roles and/or responsibilities assigned to the system (for example V(webserver)).
       - These subscriptions determine which monitoring checks are executed by the client, as check requests are sent to subscriptions.
       - The subscriptions array items must be strings.
   safe_mode:
@@ -69,7 +69,7 @@ options:
   keepalive:
     type: dict
     description:
-      - The keepalive definition scope, used to configure Sensu client keepalives behavior (e.g. keepalive thresholds, etc).
+      - The keepalive definition scope, used to configure Sensu client keepalives behavior (for example keepalive thresholds and so).
   registration:
     type: dict
     description:

plugins/modules/sensu_handler.py

@@ -80,24 +80,24 @@ options:
     type: str
     description:
       - The handler command to be executed.
-      - The event data is passed to the process via STDIN.
+      - The event data is passed to the process using STDIN.
-      - 'NOTE: the command attribute is only required for Pipe handlers (i.e. handlers configured with "type": "pipe").'
+      - 'NOTE: the O(command) attribute is only required for Pipe handlers (that is, handlers configured with O(type=pipe)).'
   socket:
     type: dict
     description:
       - The socket definition scope, used to configure the TCP/UDP handler socket.
-      - 'NOTE: the socket attribute is only required for TCP/UDP handlers (i.e. handlers configured with "type": "tcp" or "type": "udp").'
+      - 'NOTE: the O(socket) attribute is only required for TCP/UDP handlers (that is, handlers configured with O(type=tcp) or O(type=udp)).'
   pipe:
     type: dict
     description:
       - The pipe definition scope, used to configure the Sensu transport pipe.
-      - 'NOTE: the pipe attribute is only required for Transport handlers (i.e. handlers configured with "type": "transport").'
+      - 'NOTE: the O(pipe) attribute is only required for Transport handlers (that is, handlers configured with O(type=transport)).'
   handlers:
     type: list
     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 (that is, handlers configured with O(type=set)).'
+      - 'NOTE: the O(handlers) attribute is only required for handler sets (that is, handlers configured with O(type=set)).'
 """
 
 EXAMPLES = r"""

plugins/modules/sensu_silence.py

@@ -14,7 +14,7 @@ module: sensu_silence
 author: Steven Bambling (@smbambling)
 short_description: Manage Sensu silence entries
 description:
-  - Create and clear (delete) a silence entries via the Sensu API for subscriptions and checks.
+  - Create and clear (delete) a silence entries using the Sensu API for subscriptions and checks.
 extends_documentation_fragment:
   - community.general.attributes
 attributes:
@@ -46,7 +46,7 @@ options:
   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 using the Sensu API.
     default: present
     choices: ['present', 'absent']
   subscription:

plugins/modules/sensu_subscription.py

@@ -37,7 +37,7 @@ options:
   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:

plugins/modules/slack.py

@@ -19,7 +19,7 @@ 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) using the Incoming WebHook integration.
 author: "Ramon de la Fuente (@ramondelafuente)"
 extends_documentation_fragment:
   - community.general.attributes

plugins/modules/spotinst_aws_elastigroup.py

@@ -326,7 +326,7 @@ options:
 
   tenancy:
     description:
-      - Dedicated vs shared tenancy.
+      - Dedicated or shared tenancy.
       - 'The available choices are: V(default), V(dedicated).'
     type: str
 

plugins/modules/stacki_host.py

@@ -12,7 +12,7 @@ DOCUMENTATION = r"""
 module: stacki_host
 short_description: Add or remove host to stacki front-end
 description:
-  - Use this module to add or remove hosts to a stacki front-end via API.
+  - Use this module to add or remove hosts to a stacki front-end using API.
   - Information on stacki can be found at U(https://github.com/StackIQ/stacki).
 extends_documentation_fragment:
   - community.general.attributes
@@ -119,7 +119,7 @@ EXAMPLES = r"""
 
 RETURN = r"""
 changed:
-  description: Response to whether or not the api call completed successfully.
+  description: Response to whether or not the API call completed successfully.
   returned: always
   type: bool
   sample: true

plugins/modules/sudoers.py

@@ -52,7 +52,7 @@ options:
     version_added: 8.4.0
   nopassword:
     description:
-      - Whether a password will be required to run the sudo'd command.
+      - Whether a password is required when command is run with sudo.
     default: true
     type: bool
   setenv:

plugins/modules/supervisorctl.py

@@ -11,9 +11,9 @@ __metaclass__ = type
 
 DOCUMENTATION = r"""
 module: supervisorctl
-short_description: Manage the state of a program or group of programs running via supervisord
+short_description: Manage the state of a program or group of programs managed by C(supervisord).
 description:
-  - Manage the state of a program or group of programs running via supervisord.
+  - Manage the state of a program or group of programs managed by C(supervisord).
 extends_documentation_fragment:
   - community.general.attributes
 attributes:

plugins/modules/svr4pkg.py

@@ -36,7 +36,7 @@ options:
     description:
       - Whether to install (V(present)), or remove (V(absent)) a package.
       - If the package is to be installed, then O(src) is required.
-      - The SVR4 package system doesn't provide an upgrade operation. You need to uninstall the old, then install the new package.
+      - The SVR4 package system does not provide an upgrade operation. You need to uninstall the old, then install the new package.
     required: true
     choices: ["present", "absent"]
     type: str

plugins/modules/swupd.py

@@ -30,7 +30,8 @@ options:
     type: str
   format:
     description:
-      - The format suffix for version file downloads. For example [1,2,3,staging,etc]. If not specified, the default format is used.
+      - The format suffix for version file downloads. For example V(1), V(2), V(3), and so on, or the special value V(staging).
+        If not specified, the default format is used.
     type: str
   manifest:
     description:

plugins/modules/telegram.py

@@ -15,10 +15,10 @@ author:
   - "Artem Feofanov (@tyouxa)"
   - "Nikolai Lomov (@lomserman)"
 
-short_description: Send notifications via telegram
+short_description: Send notifications using telegram
 
 description:
-  - Send notifications via telegram bot, to a verified group or user.
+  - Send notifications using telegram bot, to a verified group or user.
   - Also, the user may try to use any other telegram bot API method, if you specify O(api_method) argument.
 notes:
   - You will require a telegram account and create telegram bot to use this module.

plugins/modules/terraform.py

@@ -117,7 +117,7 @@ options:
     type: int
   force_init:
     description:
-      - To avoid duplicating infra, if a state file can't be found this will force a C(terraform init). Generally, this should be turned off unless
+      - To avoid duplicating infra, if a state file cannot be found this will force a C(terraform init). Generally, this should be turned off unless
         you intend to provision an entirely new Terraform deployment.
     default: false
     type: bool
@@ -250,7 +250,7 @@ outputs:
     type:
       type: str
       returned: always
-      description: The type of the value (string, int, etc).
+      description: The type of the value (string, int, and so on).
     value:
       type: str
       returned: always

plugins/modules/twilio.py

@@ -16,7 +16,7 @@ description:
   - Sends a text message to a phone number through the Twilio messaging API.
 notes:
   - This module is non-idempotent because it sends an email through the external API. It is idempotent only in the case that the module fails.
-  - Like the other notification modules, this one requires an external dependency to work. In this case, you'll need a Twilio account with a purchased
+  - Like the other notification modules, this one requires an external dependency to work. In this case, you need a Twilio account with a purchased
     or verified phone number to send the text message.
 extends_documentation_fragment:
   - community.general.attributes

plugins/modules/udm_dns_record.py

@@ -14,9 +14,9 @@ DOCUMENTATION = r"""
 module: udm_dns_record
 author:
   - Tobias Rüetschi (@keachi)
-short_description: Manage dns entries on a univention corporate server
+short_description: Manage DNS entries on a univention corporate server
 description:
-  - This module allows to manage dns records on a univention corporate server (UCS). It uses the Python API of the UCS to create a new object
+  - This module allows to manage DNS records on a univention corporate server (UCS). It uses the Python API of the UCS to create a new object
     or edit it.
 requirements:
   - Univention
@@ -34,7 +34,7 @@ options:
     default: "present"
     choices: [present, absent]
     description:
-      - Whether the dns record is present or not.
+      - Whether the DNS record is present or not.
   name:
     type: str
     required: true

plugins/modules/udm_dns_zone.py

@@ -14,9 +14,9 @@ DOCUMENTATION = r"""
 module: udm_dns_zone
 author:
   - Tobias Rüetschi (@keachi)
-short_description: Manage dns zones on a univention corporate server
+short_description: Manage DNS zones on a univention corporate server
 description:
-  - This module allows to manage dns zones on a univention corporate server (UCS). It uses the Python API of the UCS to create a new object or
+  - This module allows to manage DNS zones on a univention corporate server (UCS). It uses the Python API of the UCS to create a new object or
     edit it.
 extends_documentation_fragment:
   - community.general.attributes

plugins/modules/utm_dns_host.py

@@ -14,10 +14,10 @@ module: utm_dns_host
 author:
   - Johannes Brunswicker (@MatrixCrawler)
 
-short_description: Create, update or destroy dns entry in Sophos UTM
+short_description: Create, update or destroy DNS entry in Sophos UTM
 
 description:
-  - Create, update or destroy a dns entry in SOPHOS UTM.
+  - Create, update or destroy a DNS entry in SOPHOS UTM.
   - This module needs to have the REST Ability of the UTM to be activated.
 attributes:
   check_mode:
@@ -44,12 +44,12 @@ options:
   comment:
     type: str
     description:
-      - An optional comment to add to the dns host object.
+      - An optional comment to add to the DNS host object.
     default: ''
   hostname:
     type: str
     description:
-      - The hostname for the dns host object.
+      - The hostname for the DNS host object.
   interface:
     type: str
     description:
@@ -68,7 +68,7 @@ options:
   timeout:
     type: int
     description:
-      - The timeout for the utm to resolve the ip address for the hostname again.
+      - The timeout for the UTM to resolve the IP address for the hostname again.
     default: 0
 
 extends_documentation_fragment:

plugins/modules/vdo.py

@@ -50,7 +50,7 @@ options:
       - The C(activate) status for a VDO volume. If this is set to V(false), the VDO volume cannot be started, and it will not start on system
         startup. However, on initial creation, a VDO volume with "activated" set to "off" will be running, until stopped. This is the default
         behavior of the C(vdo create) command; it provides the user an opportunity to write a base amount of metadata (filesystem, LVM headers,
-        etc.) to the VDO volume prior to stopping the volume, and leaving it deactivated until ready to use.
+        and so on) to the VDO volume prior to stopping the volume, and leaving it deactivated until ready to use.
     type: bool
   running:
     description:

plugins/modules/vertica_user.py

@@ -49,7 +49,7 @@ options:
     type: bool
   ldap:
     description:
-      - Set to true if users are authenticated via LDAP.
+      - Set to V(true) if users are authenticated using LDAP.
       - The user will be created with password expired and set to V($ldap$).
     type: bool
   roles:

plugins/modules/vmadm.py

@@ -106,7 +106,7 @@ options:
   force:
     required: false
     description:
-      - Force a particular action (i.e. stop or delete a VM).
+      - Force a particular action (in other words, stop or delete a VM).
     type: bool
   fs_allowed:
     required: false

plugins/modules/wakeonlan.py

@@ -44,7 +44,7 @@ todo:
 notes:
   - This module sends a magic packet, without knowing whether it worked.
   - Only works if the target system was properly configured for Wake-on-LAN (in the BIOS and/or the OS).
-  - Some BIOSes have a different (configurable) Wake-on-LAN boot order (i.e. PXE first).
+  - Some BIOSes have a different (configurable) Wake-on-LAN boot order (in other words, PXE first).
 seealso:
   - module: community.windows.win_wakeonlan
 author:

plugins/modules/xcc_redfish_command.py

@@ -16,9 +16,9 @@ description:
   - Builds Redfish URIs locally and sends them to remote OOB controllers to perform an action or get information back or update a configuration
     attribute.
   - Manages virtual media.
-  - Supports getting information back via GET method.
+  - Supports getting information back using GET method.
-  - Supports updating a configuration attribute via PATCH method.
+  - Supports updating a configuration attribute using PATCH method.
-  - Supports performing an action via POST method.
+  - Supports performing an action using POST method.
 extends_documentation_fragment:
   - community.general.attributes
 attributes:

plugins/modules/xenserver_guest.py

@@ -27,9 +27,9 @@ notes:
     are accessing XenServer host in trusted environment or use C(https://) scheme explicitly.'
   - 'To use C(https://) scheme for O(hostname) you have to either import host certificate to your OS certificate store or use O(validate_certs=false)
     which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.'
-  - 'Network configuration inside a guest OS, by using O(networks[].type), O(networks[].ip), O(networks[].gateway) etc. parameters, is supported
+  - 'Network configuration inside a guest OS, by using parameters O(networks[].type), O(networks[].ip), O(networks[].gateway) and so on, is supported
     on XenServer 7.0 or newer for Windows guests by using official XenServer Guest agent support for network configuration. The module will try
-    to detect if such support is available and utilize it, else it will use a custom method of configuration via xenstore. Since XenServer Guest
+    to detect if such support is available and utilize it, else it will use a custom method of configuration using xenstore. Since XenServer Guest
     agent only support None and Static types of network configuration, where None means DHCP configured interface, O(networks[].type) and O(networks[].type6)
     values V(none) and V(dhcp) have same effect. More info here:
     U(https://www.citrix.com/community/citrix-developer/citrix-hypervisor-developer/citrix-hypervisor-developing-products/citrix-hypervisor-staticip.html).'
@@ -211,7 +211,7 @@ options:
       type:
         description:
           - Type of IPv4 assignment. Value V(none) means whatever is default for OS.
-          - On some operating systems it could be DHCP configured (e.g. Windows) or unconfigured interface (e.g. Linux).
+          - On some operating systems it could be DHCP configured (for example Windows) or unconfigured interface (for example Linux).
         type: str
         choices: [none, dhcp, static]
       ip: