p[a-e]*: normalize docs (#9372)

* p[a-e]*: normalize docs * Update plugins/modules/packet_volume.py Co-authored-by: Felix Fontein <felix@fontein.de> --------- Co-authored-by: Felix Fontein <felix@fontein.de>
2024-12-26 20:22:24 +13:00 · 2024-12-26 20:22:24 +13:00 · bef82e28a2
parent d96e56048f
commit bef82e28a2
17 changed files with 867 additions and 945 deletions
--- a/plugins/modules/pacemaker_cluster.py
+++ b/plugins/modules/pacemaker_cluster.py
@ -8,15 +8,13 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 ---
 module: pacemaker_cluster
 short_description: Manage pacemaker clusters
 author:
  - Mathieu Bultel (@matbu)
 description:
-  - This module can manage a pacemaker cluster and nodes from Ansible using
+  - This module can manage a pacemaker cluster and nodes from Ansible using the pacemaker CLI.
    the pacemaker cli.
 extends_documentation_fragment:
  - community.general.attributes
 attributes:
@ -27,27 +25,26 @@ attributes:
 options:
  state:
    description:
-        - Indicate desired state of the cluster
+      - Indicate desired state of the cluster.
-      choices: [ cleanup, offline, online, restart ]
+    choices: [cleanup, offline, online, restart]
    type: str
  node:
    description:
-        - Specify which node of the cluster you want to manage. None == the
+      - Specify which node of the cluster you want to manage. V(null) == the cluster status itself, V(all) == check the status of all nodes.
          cluster status itself, 'all' == check the status of all nodes.
    type: str
  timeout:
    description:
-        - Timeout when the module should considered that the action has failed
+      - Timeout when the module should considered that the action has failed.
    default: 300
    type: int
  force:
    description:
-        - Force the change of the cluster state
+      - Force the change of the cluster state.
    type: bool
    default: true
-'''
+"""
-EXAMPLES = '''
+
---
+EXAMPLES = r"""
 - name: Set cluster Online
  hosts: localhost
  gather_facts: false
@ -55,24 +52,15 @@ EXAMPLES = '''
    - name: Get cluster state
      community.general.pacemaker_cluster:
        state: online
-'''
+"""
-RETURN = '''
+RETURN = r"""
 changed:
    description: true if the cluster state has changed
    type: bool
    returned: always
 out:
-    description: The output of the current state of the cluster. It return a
+  description: The output of the current state of the cluster. It returns a list of the nodes state.
                 list of the nodes state.
  type: str
  sample: 'out: [["  overcloud-controller-0", " Online"]]}'
  returned: always
-rc:
+"""
    description: exit code of the module
    type: bool
    returned: always
 '''
 import time
--- a/plugins/modules/packet_device.py
+++ b/plugins/modules/packet_device.py
@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 ---
 module: packet_device
 short_description: Manage a bare metal server in the Packet Host
@ -21,8 +20,6 @@ description:
  - When the machine is created it can optionally wait for public IP address, or for active state.
  - This module has a dependency on packet >= 1.0.
  - API is documented at U(https://www.packet.net/developers/api/devices).
 author:
  - Tomas Karasek (@t0mk) <tom.to.the.k@gmail.com>
  - Matt Baldwin (@baldwinSPC) <baldwin@stackpointcloud.com>
@ -45,7 +42,7 @@ options:
  count:
    description:
-      - The number of devices to create. Count number can be included in hostname via the %d string formatter.
+      - The number of devices to create. Count number can be included in hostname using the C(%d) string formatter.
    default: 1
    type: int
@ -122,7 +119,7 @@ options:
  user_data:
    description:
-      - Userdata blob made available to the machine
+      - Userdata blob made available to the machine.
    type: str
  wait_for_public_IPv:
@ -130,7 +127,7 @@ options:
      - Whether to wait for the instance to be assigned a public IPv4/IPv6 address.
      - If set to 4, it will wait until IPv4 is assigned to the instance.
      - If set to 6, wait until public IPv6 is assigned to the instance.
-    choices: [4,6]
+    choices: [4, 6]
    type: int
  wait_timeout:
@ -157,10 +154,9 @@ options:
 requirements:
  - "packet-python >= 1.35"
 """
-'''
+EXAMPLES = r"""
 EXAMPLES = '''
 # All the examples assume that you have your Packet API token in environment variable PACKET_API_TOKEN.
 # You can also pass it to the auth_token parameter of the module instead.
@ -256,11 +252,11 @@ EXAMPLES = '''
          - 1fb4faf8-a638-4ac7-8f47-86fe514c30d8
          - 2eb4faf8-a638-4ac7-8f47-86fe514c3043
          - 6bb4faf8-a638-4ac7-8f47-86fe514c301f
-'''
+"""
-RETURN = '''
+RETURN = r"""
 changed:
-    description: True if a device was altered in any way (created, modified or removed)
+  description: True if a device was altered in any way (created, modified or removed).
  type: bool
  sample: true
  returned: success
@ -280,7 +276,7 @@ devices:
        "public_ipv6": "2604:1380:2:5200::3"
      }
  returned: success
-'''  # NOQA
+"""
 import os
--- a/plugins/modules/packet_ip_subnet.py
+++ b/plugins/modules/packet_ip_subnet.py
@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 ---
 module: packet_ip_subnet
 short_description: Assign IP subnet to a bare metal server
@ -21,7 +20,6 @@ description:
  - IPv4 subnets must come from already reserved block.
  - IPv6 subnets must come from publicly routable /56 block from your project.
  - See U(https://support.packet.com/kb/articles/elastic-ips) for more info on IP block reservation.
 version_added: '0.2.0'
 author:
@ -77,7 +75,8 @@ options:
  state:
    description:
      - Desired state of the IP subnet on the specified device.
-      - With O(state=present), you must specify either O(hostname) or O(device_id). Subnet with given CIDR will then be assigned to the specified device.
+      - With O(state=present), you must specify either O(hostname) or O(device_id). Subnet with given CIDR will then be assigned to the specified
        device.
      - With O(state=absent), you can specify either O(hostname) or O(device_id). The subnet will be removed from specified devices.
      - If you leave both O(hostname) and O(device_id) empty, the subnet will be removed from any device it's assigned to.
    choices: ['present', 'absent']
@ -86,9 +85,9 @@ options:
 requirements:
  - "packet-python >= 1.35"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
 # All the examples assume that you have your Packet API token in env var PACKET_API_TOKEN.
 # You can also pass it to the auth_token parameter of the module instead.
@ -120,9 +119,9 @@ EXAMPLES = '''
        project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
        cidr: "147.75.201.78/32"
        state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
 changed:
  description: True if an IP address assignments were altered in any way (created or removed).
  type: bool
@ -140,7 +139,7 @@ subnet:
  sample:
    address: 147.75.90.241
    address_family: 4
-    assigned_to: { href : /devices/61f9aa5e-0530-47f5-97c2-113828e61ed0 }
+    assigned_to: {href: /devices/61f9aa5e-0530-47f5-97c2-113828e61ed0}
    cidr: 31
    created_at: '2017-08-07T15:15:30Z'
    enabled: true
@ -153,7 +152,7 @@ subnet:
    network: 147.75.90.240
    public: true
  returned: success
-'''
+"""
 import uuid
--- a/plugins/modules/packet_project.py
+++ b/plugins/modules/packet_project.py
@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 ---
 module: packet_project
 short_description: Create/delete a project in Packet host
@ -19,7 +18,6 @@ short_description: Create/delete a project in Packet host
 description:
  - Create/delete a project in Packet host.
  - API is documented at U(https://www.packet.com/developers/api/#projects).
 version_added: '0.2.0'
 author:
@ -77,10 +75,9 @@ options:
 requirements:
  - "packet-python >= 1.40"
 """
-'''
+EXAMPLES = r"""
 EXAMPLES = '''
 # All the examples assume that you have your Packet API token in env var PACKET_API_TOKEN.
 # You can also pass the api token in module param auth_token.
@ -110,9 +107,9 @@ EXAMPLES = '''
    community.general.packet_project:
      name: "newer project"
      payment_method: "the other visa"
-'''
+"""
-RETURN = '''
+RETURN = r"""
 changed:
  description: True if a project was created or removed.
  type: bool
@ -128,7 +125,7 @@ id:
  description: UUID of addressed project.
  type: str
  returned: success
-'''
+"""
 from ansible.module_utils.basic import AnsibleModule, env_fallback
 from ansible.module_utils.common.text.converters import to_native
--- a/plugins/modules/packet_sshkey.py
+++ b/plugins/modules/packet_sshkey.py
@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 ---
 module: packet_sshkey
 short_description: Create/delete an SSH key in Packet host
 description:
@ -49,7 +48,7 @@ options:
    type: str
  key:
    description:
-    - Public Key string ({type} {base64 encoded key} {description}).
+      - Public Key string (V({type} {base64 encoded key} {description})).
    type: str
  key_file:
    description:
@ -58,10 +57,9 @@ options:
 requirements:
  - packet-python
 """
-'''
+EXAMPLES = r"""
 EXAMPLES = '''
 # All the examples assume that you have your Packet API token in env var PACKET_API_TOKEN.
 # You can also pass the api token in module param auth_token.
@ -84,9 +82,9 @@ EXAMPLES = '''
    community.general.packet_sshkey:
      state: absent
      id: eef49903-7a09-4ca1-af67-4087c29ab5b6
-'''
+"""
-RETURN = '''
+RETURN = r"""
 changed:
  description: True if a sshkey was created or removed.
  type: bool
@ -99,12 +97,12 @@ sshkeys:
      {
        "fingerprint": "5c:93:74:7c:ed:07:17:62:28:75:79:23:d6:08:93:46",
        "id": "41d61bd8-3342-428b-a09c-e67bdd18a9b7",
-            "key": "ssh-dss AAAAB3NzaC1kc3MAAACBAIfNT5S0ncP4BBJBYNhNPxFF9lqVhfPeu6SM1LoCocxqDc1AT3zFRi8hjIf6TLZ2AA4FYbcAWxLMhiBxZRVldT9GdBXile78kAK5z3bKTwq152DCqpxwwbaTIggLFhsU8wrfBsPWnDuAxZ0h7mmrCjoLIE3CNLDA/NmV3iB8xMThAAAAFQCStcesSgR1adPORzBxTr7hug92LwAAAIBOProm3Gk+HWedLyE8IfofLaOeRnbBRHAOL4z0SexKkVOnQ/LGN/uDIIPGGBDYTvXgKZT+jbHeulRJ2jKgfSpGKN4JxFQ8uzVH492jEiiUJtT72Ss1dCV4PmyERVIw+f54itihV3z/t25dWgowhb0int8iC/OY3cGodlmYb3wdcQAAAIBuLbB45djZXzUkOTzzcRDIRfhaxo5WipbtEM2B1fuBt2gyrvksPpH/LK6xTjdIIb0CxPu4OCxwJG0aOz5kJoRnOWIXQGhH7VowrJhsqhIc8gN9ErbO5ea8b1L76MNcAotmBDeTUiPw01IJ8MdDxfmcsCslJKgoRKSmQpCwXQtN2g== tomk@hp2",
+        "key": "ssh-dss AAAAB3NzaC1kc3MAAACBA ... MdDxfmcsCslJKgoRKSmQpCwXQtN2g== user@server",
        "label": "mynewkey33"
      }
    ]
    returned: always
-'''  # NOQA
+"""
 import os
 import uuid
--- a/plugins/modules/packet_volume.py
+++ b/plugins/modules/packet_volume.py
@ -9,8 +9,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 ---
 module: packet_volume
 short_description: Create/delete a volume in Packet host
@ -18,7 +17,6 @@ short_description: Create/delete a volume in Packet host
 description:
  - Create/delete a volume in Packet host.
  - API is documented at U(https://www.packet.com/developers/api/#volumes).
 version_added: '0.2.0'
 author:
@ -55,14 +53,13 @@ options:
  name:
    description:
-      - Selector for API-generated name of the volume
+      - Selector for API-generated name of the volume.
    type: str
  description:
    description:
      - User-defined description attribute for Packet volume.
-      - "It is used used as idempotent identifier - if volume with given
+      - It is used used as idempotent identifier - if volume with given description exists, new one is not created.
        description exists, new one is not created."
    type: str
  id:
@ -72,7 +69,7 @@ options:
  plan:
    description:
-      - storage_1 for standard tier, storage_2 for premium (performance) tier.
+      - V(storage_1) for standard tier, V(storage_2) for premium (performance) tier.
      - Tiers are described at U(https://www.packet.com/cloud/storage/).
    choices: ['storage_1', 'storage_2']
    default: 'storage_1'
@ -123,10 +120,9 @@ options:
 requirements:
  - "packet-python >= 1.35"
 """
-'''
+EXAMPLES = r"""
 EXAMPLES = '''
 # All the examples assume that you have your Packet API token in env var PACKET_API_TOKEN.
 # You can also pass the api token in module param auth_token.
@ -154,11 +150,11 @@ EXAMPLES = '''
        id: "{{ result_create.id }}"
        project_id: "{{ project_id }}"
        state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
 id:
-    description: UUID of specified volume
+  description: UUID of specified volume.
  type: str
  returned: success
  sample: 53000fb2-ee46-4673-93a8-de2c2bdba33c
@ -172,7 +168,7 @@ description:
  type: str
  returned: success
  sample: "Just another volume"
-'''
+"""
 import uuid
--- a/plugins/modules/packet_volume_attachment.py
+++ b/plugins/modules/packet_volume_attachment.py
@ -10,8 +10,7 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 ---
 module: packet_volume_attachment
 short_description: Attach/detach a volume to a device in the Packet host
@ -19,10 +18,8 @@ short_description: Attach/detach a volume to a device in the Packet host
 description:
  - Attach/detach a volume to a device in the Packet host.
  - API is documented at U(https://www.packet.com/developers/api/volumes/).
-     - "This module creates the attachment route in the Packet API. In order to discover
+  - This module creates the attachment route in the Packet API. In order to discover the block devices on the server, you have to run the Attach
-       the block devices on the server, you have to run the Attach Scripts,
+    Scripts, as documented at U(https://help.packet.net/technical/storage/packet-block-storage-linux).
       as documented at U(https://help.packet.net/technical/storage/packet-block-storage-linux)."
 version_added: '0.2.0'
 author:
@ -61,7 +58,7 @@ options:
    description:
      - Selector for the volume.
      - It can be a UUID, an API-generated volume name, or user-defined description string.
-      - 'Example values: 4a347482-b546-4f67-8300-fb5018ef0c5, volume-4a347482, "my volume"'
+      - 'Example values: V(4a347482-b546-4f67-8300-fb5018ef0c5), V(volume-4a347482), V(my volume).'
    type: str
    required: true
@ -69,15 +66,14 @@ options:
    description:
      - Selector for the device.
      - It can be a UUID of the device, or a hostname.
-      - 'Example values: 98a14f7a-3d27-4478-b7cf-35b5670523f3, "my device"'
+      - 'Example values: 98a14f7a-3d27-4478-b7cf-35b5670523f3, "my device".'
    type: str
 requirements:
  - "packet-python >= 1.35"
 """
-'''
+EXAMPLES = r"""
 EXAMPLES = '''
 # All the examples assume that you have your Packet API token in env var PACKET_API_TOKEN.
 # You can also pass the api token in module param auth_token.
@ -122,9 +118,9 @@ EXAMPLES = '''
        volume: "{{ volname }}"
        device: "{{ devname }}"
        state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
 volume_id:
  description: UUID of volume addressed by the module call.
  type: str
@ -134,7 +130,7 @@ device_id:
  description: UUID of device addressed by the module call.
  type: str
  returned: success
-'''
+"""
 import uuid
--- a/plugins/modules/pacman.py
+++ b/plugins/modules/pacman.py
@ -12,8 +12,7 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
-DOCUMENTATION = """
+DOCUMENTATION = r"""
 ---
 module: pacman
 short_description: Manage packages with I(pacman)
 description:
@ -33,9 +32,8 @@ attributes:
 options:
  name:
    description:
-            - Name or list of names of the package(s) or file(s) to install, upgrade, or remove.
+      - Name or list of names of the package(s) or file(s) to install, upgrade, or remove. Cannot be used in combination with O(upgrade).
-              Cannot be used in combination with O(upgrade).
+    aliases: [package, pkg]
        aliases: [ package, pkg ]
    type: list
    elements: str
@ -46,22 +44,19 @@ options:
      - V(latest) will update the specified package if it is not of the latest available version.
      - V(absent) and V(removed) will remove the specified package.
    default: present
-        choices: [ absent, installed, latest, present, removed ]
+    choices: [absent, installed, latest, present, removed]
    type: str
  force:
    description:
-            - When removing packages, forcefully remove them, without any checks.
+      - When removing packages, forcefully remove them, without any checks. Same as O(extra_args="--nodeps --nodeps").
-              Same as O(extra_args="--nodeps --nodeps").
+      - When combined with O(update_cache), force a refresh of all package databases. Same as O(update_cache_extra_args="--refresh --refresh").
            - When combined with O(update_cache), force a refresh of all package databases.
              Same as O(update_cache_extra_args="--refresh --refresh").
    default: false
    type: bool
  remove_nosave:
    description:
-            - When removing packages, do not save modified configuration files as C(.pacsave) files.
+      - When removing packages, do not save modified configuration files as C(.pacsave) files. (passes C(--nosave) to pacman).
              (passes C(--nosave) to pacman)
    version_added: 4.6.0
    default: false
    type: bool
@ -69,9 +64,8 @@ options:
  executable:
    description:
      - Path of the binary to use. This can either be C(pacman) or a pacman compatible AUR helper.
-            - Pacman compatibility is unfortunately ill defined, in particular, this modules makes
+      - Pacman compatibility is unfortunately ill defined, in particular, this modules makes extensive use of the C(--print-format) directive
-              extensive use of the C(--print-format) directive which is known not to be implemented by
+        which is known not to be implemented by some AUR helpers (notably, C(yay)).
              some AUR helpers (notably, C(yay)).
      - Beware that AUR helpers might behave unexpectedly and are therefore not recommended.
    default: pacman
    type: str
@ -88,9 +82,8 @@ options:
      - Whether or not to refresh the master package lists.
      - This can be run as part of a package installation or as a separate step.
      - If not specified, it defaults to V(false).
-            - Please note that this option only had an influence on the module's C(changed) state
+      - Please note that this option only had an influence on the module's C(changed) state if O(name) and O(upgrade) are not specified before
-              if O(name) and O(upgrade) are not specified before community.general 5.0.0.
+        community.general 5.0.0. See the examples for how to keep the old behavior.
              See the examples for how to keep the old behavior.
    type: bool
  update_cache_extra_args:
@ -101,8 +94,7 @@ options:
  upgrade:
    description:
-            - Whether or not to upgrade the whole system.
+      - Whether or not to upgrade the whole system. Cannot be used in combination with O(name).
              Cannot be used in combination with O(name).
      - If not specified, it defaults to V(false).
    type: bool
@ -115,7 +107,7 @@ options:
  reason:
    description:
      - The install reason to set for the packages.
-        choices: [ dependency, explicit ]
+    choices: [dependency, explicit]
    type: str
    version_added: 5.4.0
@ -124,32 +116,29 @@ options:
      - Set the install reason for V(all) packages or only for V(new) packages.
      - In case of O(state=latest) already installed packages which will be updated to a newer version are not counted as V(new).
    default: new
-        choices: [ all, new ]
+    choices: [all, new]
    type: str
    version_added: 5.4.0
 notes:
-  - When used with a C(loop:) each package will be processed individually,
+  - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the O(name)
-    it is much more efficient to pass the list directly to the O(name) option.
+    option.
-  - To use an AUR helper (O(executable) option), a few extra setup steps might be required beforehand.
+  - To use an AUR helper (O(executable) option), a few extra setup steps might be required beforehand. For example, a dedicated build user with
-    For example, a dedicated build user with permissions to install packages could be necessary.
+    permissions to install packages could be necessary.
-  - >
+  - 'In the tests, while using C(yay) as the O(executable) option, the module failed to install AUR packages with the error: C(error: target not
-    In the tests, while using C(yay) as the O(executable) option, the module failed to install AUR packages
+    found: <pkg>).'
    with the error: C(error: target not found: <pkg>).
 """
-RETURN = """
+RETURN = r"""
 packages:
  description:
    - A list of packages that have been changed.
-        - Before community.general 4.5.0 this was only returned when O(upgrade=true).
+    - Before community.general 4.5.0 this was only returned when O(upgrade=true). In community.general 4.5.0, it was sometimes omitted when the
-          In community.general 4.5.0, it was sometimes omitted when the package list is empty,
+      package list is empty, but since community.general 4.6.0 it is always returned when O(name) is specified or O(upgrade=true).
          but since community.general 4.6.0 it is always returned when O(name) is specified or
          O(upgrade=true).
  returned: success and O(name) is specified or O(upgrade=true)
  type: list
  elements: str
-    sample: [ package, other-package ]
+  sample: [package, other-package]
 cache_updated:
  description:
@ -177,7 +166,7 @@ stderr:
  version_added: 4.1.0
 """
-EXAMPLES = """
+EXAMPLES = r"""
 - name: Install package foo from repo
  community.general.pacman:
    name: foo
--- a/plugins/modules/pacman_key.py
+++ b/plugins/modules/pacman_key.py
@ -8,8 +8,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 ---
 module: pacman_key
 author:
  - George Rawlinson (@grawlinson)
@ -81,11 +80,11 @@ options:
    description:
      - Ensures that the key is present (added) or absent (revoked).
    default: present
-        choices: [ absent, present ]
+    choices: [absent, present]
    type: str
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Import a key via local file
  community.general.pacman_key:
    id: 01234567890ABCDE01234567890ABCDE12345678
@ -119,9 +118,9 @@ EXAMPLES = '''
  community.general.pacman_key:
    id: 01234567890ABCDE01234567890ABCDE12345678
    state: absent
-'''
+"""
-RETURN = r''' # '''
+RETURN = r""" # """
 import os.path
 import tempfile
--- a/plugins/modules/pagerduty.py
+++ b/plugins/modules/pagerduty.py
@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 module: pagerduty
 short_description: Create PagerDuty maintenance windows
 description:
-    - This module will let you create PagerDuty maintenance windows
+  - This module will let you create PagerDuty maintenance windows.
 author:
  - "Andrew Newdigate (@suprememoocow)"
  - "Dylan Silva (@thaumos)"
@ -35,7 +34,7 @@ options:
    description:
      - Create a maintenance window or get a list of ongoing windows.
    required: true
-        choices: [ "running", "started", "ongoing", "absent" ]
+    choices: ["running", "started", "ongoing", "absent"]
  name:
    type: str
    description:
@ -58,7 +57,7 @@ options:
    elements: str
    description:
      - A comma separated list of PagerDuty service IDs.
-        aliases: [ services ]
+    aliases: [services]
  window_id:
    type: str
    description:
@ -80,13 +79,12 @@ options:
    default: Created by Ansible
  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
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: List ongoing maintenance windows using a token
  community.general.pagerduty:
    name: companyabc
@ -143,7 +141,7 @@ EXAMPLES = '''
    token: yourtoken
    state: absent
    window_id: "{{ pd_window.result.maintenance_windows[0].id }}"
-'''
+"""
 import datetime
 import json
--- a/plugins/modules/pagerduty_alert.py
+++ b/plugins/modules/pagerduty_alert.py
@ -8,12 +8,11 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 module: pagerduty_alert
 short_description: Trigger, acknowledge or resolve PagerDuty incidents
 description:
-    - This module will let you trigger, acknowledge or resolve a PagerDuty incident by sending events
+  - This module will let you trigger, acknowledge or resolve a PagerDuty incident by sending events.
 author:
  - "Amanpreet Singh (@ApsOps)"
  - "Xiao Shen (@xshen1)"
@ -64,7 +63,7 @@ options:
    description:
      - The API version we want to use to run the module.
      - V1 is more limited with option we can provide to trigger incident.
-            - V2 has more variables for example, O(severity), O(source), O(custom_details), etc.
+      - V2 has more variables for example, O(severity), O(source), O(custom_details) and so on.
    default: 'v1'
    choices:
      - 'v1'
@ -96,9 +95,9 @@ options:
  desc:
    type: str
    description:
-            - For O(state=triggered) - Required. Short description of the problem that led to this trigger. This field (or a truncated version)
+      - For O(state=triggered) - Required. Short description of the problem that led to this trigger. This field (or a truncated version) will
-              will be used when generating phone calls, SMS messages and alert emails. It will also appear on the incidents tables in the PagerDuty UI.
+        be used when generating phone calls, SMS messages and alert emails. It will also appear on the incidents tables in the PagerDuty UI. The
-              The maximum length is 1024 characters.
+        maximum length is 1024 characters.
      - For O(state=acknowledged) or O(state=resolved) - Text that will appear in the incident's log associated with this event.
    required: false
    default: Created via Ansible
@ -112,22 +111,22 @@ options:
    type: str
    description:
      - Identifies the incident to which this O(state) should be applied.
-            - For O(state=triggered) - If there's no open (i.e. unresolved) incident with this key, a new one will be created. If there's already an
+      - For O(state=triggered) - If there is no open (in other words unresolved) incident with this key, a new one will be created. If there is already an
        open incident with a matching key, this event will be appended to that incident's log. The event key provides an easy way to 'de-dup'
        problem reports. If no O(incident_key) is provided, then it will be generated by PagerDuty.
-            - For O(state=acknowledged) or O(state=resolved) - This should be the incident_key you received back when the incident was first opened by a
+      - For O(state=acknowledged) or O(state=resolved) - This should be the incident_key you received back when the incident was first opened
-              trigger event. Acknowledge events referencing resolved or nonexistent incidents will be discarded.
+        by a trigger event. Acknowledge events referencing resolved or nonexistent incidents will be discarded.
    required: false
  link_url:
    type: str
    description:
-        - Relevant link url to the alert. For example, the website or the job link.
+      - Relevant link URL to the alert. For example, the website or the job link.
    required: false
    version_added: 7.4.0
  link_text:
    type: str
    description:
-        - A short description of the link_url.
+      - A short description of the O(link_url).
    required: false
    version_added: 7.4.0
  source:
@ -149,9 +148,9 @@ options:
      - 'error'
      - 'info'
    version_added: 7.4.0
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Trigger an incident with just the basic options
  community.general.pagerduty_alert:
    name: companyabc
@ -226,7 +225,7 @@ EXAMPLES = '''
    integration_key: xxx
    incident_key: somekey
    state: resolved
-'''
+"""
 import json
 from ansible.module_utils.basic import AnsibleModule
--- a/plugins/modules/pagerduty_change.py
+++ b/plugins/modules/pagerduty_change.py
@ -8,7 +8,7 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 module: pagerduty_change
 short_description: Track a code or infrastructure change as a PagerDuty change event
 version_added: 1.3.0
@ -31,8 +31,7 @@ attributes:
 options:
  integration_key:
    description:
-      - The integration key that identifies the service the change was made to.
+      - The integration key that identifies the service the change was made to. This can be found by adding an integration to a service in PagerDuty.
        This can be found by adding an integration to a service in PagerDuty.
    required: true
    type: str
  summary:
@ -82,14 +81,14 @@ options:
    type: str
  validate_certs:
    description:
-      - If V(false), SSL certificates for the target URL will not be validated.
+      - If V(false), SSL certificates for the target URL will not be validated. This should only be used on personally controlled sites using
-        This should only be used on personally controlled sites using self-signed certificates.
+        self-signed certificates.
    required: false
    default: true
    type: bool
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Track the deployment as a PagerDuty change event
  community.general.pagerduty_change:
    integration_key: abc123abc123abc123abc123abc123ab
@ -106,7 +105,7 @@ EXAMPLES = '''
    environment: production
    link_url: https://github.com/ansible-collections/community.general/pull/1269
    link_text: View changes on GitHub
-'''
+"""
 from ansible.module_utils.urls import fetch_url
 from ansible.module_utils.basic import AnsibleModule
--- a/plugins/modules/pagerduty_user.py
+++ b/plugins/modules/pagerduty_user.py
@ -8,8 +8,7 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: pagerduty_user
 short_description: Manage a user account on PagerDuty
 description:
@ -52,7 +51,7 @@ options:
  state:
    description:
      - State of the user.
-            - On V(present), it creates a user if the user doesn't exist.
+      - On V(present), it creates a user if the user does not exist.
      - On V(absent), it removes a user if the account exists.
    choices: ['present', 'absent']
    default: 'present'
@ -63,9 +62,9 @@ options:
      - Required if O(state=present).
    type: list
    elements: str
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Create a user account on PagerDuty
  community.general.pagerduty_user:
    access_token: 'Your_Access_token'
@ -81,9 +80,9 @@ EXAMPLES = r'''
    pd_user: user_full_name
    pd_email: user_email
    state: "absent"
-'''
+"""
-RETURN = r''' # '''
+RETURN = r""" # """
 from os import path
 from ansible.module_utils.basic import AnsibleModule
--- a/plugins/modules/pam_limits.py
+++ b/plugins/modules/pam_limits.py
@ -8,11 +8,10 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: pam_limits
 author:
- "Sebastien Rohaut (@usawa)"
+  - "Sebastien Rohaut (@usawa)"
 short_description: Modify Linux PAM limits
 description:
  - The M(community.general.pam_limits) module modifies PAM limits.
@ -38,7 +37,7 @@ options:
    description:
      - Limit type, see C(man 5 limits.conf) for an explanation.
    required: true
-    choices: [ "hard", "soft", "-" ]
+    choices: ["hard", "soft", "-"]
  limit_item:
    type: str
    description:
@ -74,24 +73,21 @@ options:
    required: true
  backup:
    description:
-      - Create a backup file including the timestamp information so you can get
+      - Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
        the original file back if you somehow clobbered it incorrectly.
    required: false
    type: bool
    default: false
  use_min:
    description:
      - If set to V(true), the minimal value will be used or conserved.
-      - If the specified value is inferior to the value in the file,
+      - If the specified value is inferior to the value in the file, file content is replaced with the new value, else content is not modified.
        file content is replaced with the new value, else content is not modified.
    required: false
    type: bool
    default: false
  use_max:
    description:
      - If set to V(true), the maximal value will be used or conserved.
-      - If the specified value is superior to the value in the file,
+      - If the specified value is superior to the value in the file, file content is replaced with the new value, else content is not modified.
        file content is replaced with the new value, else content is not modified.
    required: false
    type: bool
    default: false
@ -109,9 +105,9 @@ options:
    default: ''
 notes:
  - If O(dest) file does not exist, it is created.
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Add or modify nofile soft limit for the user joe
  community.general.pam_limits:
    domain: joe
@ -141,7 +137,7 @@ EXAMPLES = r'''
    limit_type: hard
    limit_item: nofile
    value: 39693561
-'''
+"""
 import os
 import re
--- a/plugins/modules/pamd.py
+++ b/plugins/modules/pamd.py
@ -9,15 +9,14 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 module: pamd
 author:
  - Kenneth D. Evensen (@kevensen)
 short_description: Manage PAM Modules
 description:
  - Edit PAM service's type, control, module path and module arguments.
-  - In order for a PAM rule to be modified, the type, control and
+  - In order for a PAM rule to be modified, the type, control and module_path must match an existing rule. See man(5) pam.d for details.
    module_path must match an existing rule. See man(5) pam.d for details.
 notes:
  - This module does not handle authselect profiles.
 extends_documentation_fragment:
@ -30,8 +29,7 @@ attributes:
 options:
  name:
    description:
-      - The name generally refers to the PAM service file to
+      - The name generally refers to the PAM service file to change, for example system-auth.
        change, for example system-auth.
    type: str
    required: true
  type:
@ -40,12 +38,11 @@ options:
      - The O(type), O(control), and O(module_path) options all must match a rule to be modified.
    type: str
    required: true
-    choices: [ account, -account, auth, -auth, password, -password, session, -session ]
+    choices: [account, -account, auth, -auth, password, -password, session, -session]
  control:
    description:
      - The control of the PAM rule being modified.
-      - This may be a complicated control with brackets. If this is the case, be
+      - This may be a complicated control with brackets. If this is the case, be sure to put "[bracketed controls]" in quotes.
        sure to put "[bracketed controls]" in quotes.
      - The O(type), O(control), and O(module_path) options all must match a rule to be modified.
    type: str
    required: true
@ -59,7 +56,7 @@ options:
    description:
      - The new type to assign to the new rule.
    type: str
-    choices: [ account, -account, auth, -auth, password, -password, session, -session ]
+    choices: [account, -account, auth, -auth, password, -password, session, -session]
  new_control:
    description:
      - The new control to assign to the new rule.
@ -72,25 +69,20 @@ options:
    description:
      - When O(state=updated), the O(module_arguments) will replace existing module_arguments.
      - When O(state=args_absent) args matching those listed in O(module_arguments) will be removed.
-    - When O(state=args_present) any args listed in O(module_arguments) are added if
+      - When O(state=args_present) any args listed in O(module_arguments) are added if missing from the existing rule.
-      missing from the existing rule.
+      - Furthermore, if the module argument takes a value denoted by C(=), the value will be changed to that specified in module_arguments.
    - Furthermore, if the module argument takes a value denoted by C(=),
      the value will be changed to that specified in module_arguments.
    type: list
    elements: str
  state:
    description:
-    - The default of V(updated) will modify an existing rule if type,
+      - The default of V(updated) will modify an existing rule if type, control and module_path all match an existing rule.
-      control and module_path all match an existing rule.
+      - With V(before), the new rule will be inserted before a rule matching type, control and module_path.
-    - With V(before), the new rule will be inserted before a rule matching type,
+      - Similarly, with V(after), the new rule will be inserted after an existing rulematching type, control and module_path.
      control and module_path.
    - Similarly, with V(after), the new rule will be inserted after an existing rulematching type,
      control and module_path.
      - With either V(before) or V(after) O(new_type), O(new_control), and O(new_module_path) must all be specified.
      - If state is V(args_absent) or V(args_present), O(new_type), O(new_control), and O(new_module_path) will be ignored.
      - State V(absent) will remove the rule.
    type: str
-    choices: [ absent, before, after, args_absent, args_present, updated ]
+    choices: [absent, before, after, args_absent, args_present, updated]
    default: updated
  path:
    description:
@ -99,13 +91,12 @@ options:
    default: /etc/pam.d
  backup:
    description:
-       - Create a backup file including the timestamp information so you can
+      - Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
         get the original file back if you somehow clobbered it incorrectly.
    type: bool
    default: false
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Update pamd rule's control in /etc/pam.d/system-auth
  community.general.pamd:
    name: system-auth
@ -133,8 +124,7 @@ EXAMPLES = r'''
    new_module_path: pam_faillock.so
    state: before
- name: Insert a new rule pam_wheel.so with argument 'use_uid' after an \
+- name: Insert a new rule pam_wheel.so with argument 'use_uid' after an existing rule pam_rootok.so
        existing rule pam_rootok.so
  community.general.pamd:
    name: su
    type: auth
@ -226,9 +216,9 @@ EXAMPLES = r'''
    type: auth
    module_path: pam_sss.so
    control: 'requisite'
-'''
+"""
-RETURN = r'''
+RETURN = r"""
 change_count:
  description: How many rules were changed.
  type: int
@ -236,11 +226,10 @@ change_count:
  returned: success
 backupdest:
  description:
-    - "The file name of the backup file, if created."
+    - The file name of the backup file, if created.
  returned: success
  type: str
-...
+"""
 '''
 from ansible.module_utils.basic import AnsibleModule
--- a/plugins/modules/parted.py
+++ b/plugins/modules/parted.py
@ -9,21 +9,18 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 author:
  - Fabrizio Colonna (@ColOfAbRiX)
 module: parted
 short_description: Configure block device partitions
 description:
-  - This module allows configuring block device partition using the C(parted)
+  - This module allows configuring block device partition using the C(parted) command line tool. For a full description of the fields and the
-    command line tool. For a full description of the fields and the options
+    options check the GNU parted manual.
    check the GNU parted manual.
 requirements:
  - This module requires C(parted) version 1.8.3 and above.
  - Option O(align) (except V(undefined)) requires C(parted) 2.1 or above.
-  - If the version of C(parted) is below 3.1, it requires a Linux version running
+  - If the version of C(parted) is below 3.1, it requires a Linux version running the C(sysfs) file system C(/sys/).
    the C(sysfs) file system C(/sys/).
  - Requires the C(resizepart) command when using the O(resize) parameter.
 extends_documentation_fragment:
  - community.general.attributes
@ -36,15 +33,14 @@ options:
  device:
    description:
      - The block device (disk) where to operate.
-      - Regular files can also be partitioned, but it is recommended to create a
+      - Regular files can also be partitioned, but it is recommended to create a loopback device using C(losetup) to easily access its partitions.
        loopback device using C(losetup) to easily access its partitions.
    type: str
    required: true
  align:
    description:
      - Set alignment for newly created partitions. Use V(undefined) for parted default alignment.
    type: str
-    choices: [ cylinder, minimal, none, optimal, undefined ]
+    choices: [cylinder, minimal, none, optimal, undefined]
    default: optimal
  number:
    description:
@ -53,46 +49,40 @@ options:
    type: int
  unit:
    description:
-      - Selects the current default unit that Parted will use to display
+      - Selects the current default unit that Parted will use to display locations and capacities on the disk and to interpret those given by
-        locations and capacities on the disk and to interpret those given by the
+        the user if they are not suffixed by an unit.
        user if they are not suffixed by an unit.
      - When fetching information about a disk, it is recommended to always specify a unit.
    type: str
-    choices: [ s, B, KB, KiB, MB, MiB, GB, GiB, TB, TiB, '%', cyl, chs, compact ]
+    choices: [s, B, KB, KiB, MB, MiB, GB, GiB, TB, TiB, '%', cyl, chs, compact]
    default: KiB
  label:
    description:
      - Disk label type or partition table to use.
-      - If O(device) already contains a different label, it will be changed to O(label)
+      - If O(device) already contains a different label, it will be changed to O(label) and any previous partitions will be lost.
        and any previous partitions will be lost.
      - A O(name) must be specified for a V(gpt) partition table.
    type: str
-    choices: [ aix, amiga, bsd, dvh, gpt, loop, mac, msdos, pc98, sun ]
+    choices: [aix, amiga, bsd, dvh, gpt, loop, mac, msdos, pc98, sun]
    default: msdos
  part_type:
    description:
      - May be specified only with O(label=msdos) or O(label=dvh).
      - Neither O(part_type) nor O(name) may be used with O(label=sun).
    type: str
-    choices: [ extended, logical, primary ]
+    choices: [extended, logical, primary]
    default: primary
  part_start:
    description:
-      - Where the partition will start as offset from the beginning of the disk,
+      - Where the partition will start as offset from the beginning of the disk, that is, the "distance" from the start of the disk. Negative
-        that is, the "distance" from the start of the disk. Negative numbers
+        numbers specify distance from the end of the disk.
-        specify distance from the end of the disk.
+      - The distance can be specified with all the units supported by parted (except compat) and it is case sensitive, for example V(10GiB), V(15%).
      - The distance can be specified with all the units supported by parted
        (except compat) and it is case sensitive, for example V(10GiB), V(15%).
      - Using negative values may require setting of O(fs_type) (see notes).
    type: str
    default: 0%
  part_end:
    description:
-      - Where the partition will end as offset from the beginning of the disk,
+      - Where the partition will end as offset from the beginning of the disk, that is, the "distance" from the start of the disk. Negative numbers
        that is, the "distance" from the start of the disk. Negative numbers
        specify distance from the end of the disk.
-      - The distance can be specified with all the units supported by parted
+      - The distance can be specified with all the units supported by parted (except compat) and it is case sensitive, for example V(10GiB), V(15%).
        (except compat) and it is case sensitive, for example V(10GiB), V(15%).
    type: str
    default: 100%
  name:
@ -108,7 +98,7 @@ options:
      - Whether to create or delete a partition.
      - If set to V(info) the module will only return the device information.
    type: str
-    choices: [ absent, present, info ]
+    choices: [absent, present, info]
    default: info
  fs_type:
    description:
@ -124,18 +114,15 @@ options:
    version_added: '1.3.0'
 notes:
-  - When fetching information about a new disk and when the version of parted
+  - When fetching information about a new disk and when the version of parted installed on the system is before version 3.1, the module queries
-    installed on the system is before version 3.1, the module queries the kernel
+    the kernel through C(/sys/) to obtain disk information. In this case the units CHS and CYL are not supported.
-    through C(/sys/) to obtain disk information. In this case the units CHS and
+  - Negative O(part_start) start values were rejected if O(fs_type) was not given. This bug was fixed in parted 3.2.153. If you want to use negative
-    CYL are not supported.
+    O(part_start), specify O(fs_type) as well or make sure your system contains newer parted.
-  - Negative O(part_start) start values were rejected if O(fs_type) was not given.
+"""
    This bug was fixed in parted 3.2.153. If you want to use negative O(part_start),
    specify O(fs_type) as well or make sure your system contains newer parted.
 '''
-RETURN = r'''
+RETURN = r"""
 partition_info:
-  description: Current partition information
+  description: Current partition information.
  returned: success
  type: complex
  contains:
@ -146,7 +133,7 @@ partition_info:
      description: List of device partitions.
      type: list
    script:
-      description: parted script executed by module
+      description: Parted script executed by module.
      type: str
  sample: {
      "disk": {
@ -177,9 +164,9 @@ partition_info:
      }],
      "script": "unit KiB print "
    }
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Create a new ext4 primary partition
  community.general.parted:
    device: /dev/sdb
@ -204,7 +191,7 @@ EXAMPLES = r'''
  community.general.parted:
    device: /dev/sdb
    number: 2
-    flags: [ lvm ]
+    flags: [lvm]
    state: present
    part_start: 1GiB
@ -235,7 +222,7 @@ EXAMPLES = r'''
    part_end: "100%"
    resize: true
    state: present
-'''
+"""
 from ansible.module_utils.basic import AnsibleModule
--- a/plugins/modules/pear.py
+++ b/plugins/modules/pear.py
@ -12,8 +12,7 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 ---
 module: pear
 short_description: Manage pear/pecl packages
 description:
@ -57,9 +56,9 @@ options:
    type: list
    elements: raw
    version_added: 0.2.0
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Install pear package
  community.general.pear:
    name: Net_URL2
@ -84,10 +83,9 @@ EXAMPLES = r'''
    prompts:
      - (.*)Enable internal debugging in APCu \[no\]: "yes"
- name: Install multiple pear/pecl packages at once with prompts.
+- name: Install multiple pear/pecl packages at once with prompts. Prompts will be processed on the same order as the packages order. If there
-    Prompts will be processed on the same order as the packages order.
+    is more prompts than packages, packages without prompts will be installed without any prompt expected. If there is more packages than prompts,
-    If there is more prompts than packages, packages without prompts will be installed without any prompt expected.
+    additional prompts will be ignored.
    If there is more packages than prompts, additional prompts will be ignored.
  community.general.pear:
    name: pecl/gnupg, pecl/apcu
    state: present
@ -95,10 +93,9 @@ EXAMPLES = r'''
      - I am a test prompt because gnupg doesnt asks anything
      - (.*)Enable internal debugging in APCu \[no\]: "yes"
- name: Install multiple pear/pecl packages at once skipping the first prompt.
+- name: Install multiple pear/pecl packages at once skipping the first prompt. Prompts will be processed on the same order as the packages order.
-    Prompts will be processed on the same order as the packages order.
+    If there is more prompts than packages, packages without prompts will be installed without any prompt expected. If there is more packages
-    If there is more prompts than packages, packages without prompts will be installed without any prompt expected.
+    than prompts, additional prompts will be ignored.
    If there is more packages than prompts, additional prompts will be ignored.
  community.general.pear:
    name: pecl/gnupg, pecl/apcu
    state: present
@ -115,7 +112,7 @@ EXAMPLES = r'''
  community.general.pear:
    name: Net_URL2,pecl/json_post
    state: absent
-'''
+"""
 import os