fixed hidden warnings from extra tests - batch 2 (#10027)

* fixed hidden warnings from extra tests - batch 2

* remove multiple yaml doc markers from EXAMPLE blocks

* Apply suggestions from code review

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

* Apply suggestions from code review

* Apply suggestions from code review

* dig: adjust markup for return suboptions

* Update plugins/lookup/dig.py

---------

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

plugins/inventory/proxmox.py

@@ -155,7 +155,11 @@ user: ci@pve
 token_id: gitlab-1
 token_secret: fa256e9c-26ab-41ec-82da-707a2c079829
 
+---
 # The secret can also be a vault string or passed via the environment variable TOKEN_SECRET.
+plugin: community.general.proxmox
+user: ci@pve
+token_id: gitlab-1
 token_secret: !vault |
           $ANSIBLE_VAULT;1.1;AES256
           62353634333163633336343265623632626339313032653563653165313262343931643431656138
@@ -216,7 +220,6 @@ password: "{{ lookup('community.general.random_string', base64=True) }}"
 # Note that this can easily give you wrong values as ansible_host. See further up for
 # an example where this is set to `false` and where ansible_host is set with `compose`.
 want_proxmox_nodes_ansible_host: true
-
 '''
 
 import itertools

plugins/inventory/xen_orchestra.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: xen_orchestra
 short_description: Xen Orchestra inventory source
 version_added: 4.1.0
@@ -16,27 +16,30 @@ DOCUMENTATION = '''
   - websocket-client >= 1.0.0
 description:
   - Get inventory hosts from a Xen Orchestra deployment.
-        - 'Uses a configuration file as an inventory source, it must end in C(.xen_orchestra.yml) or C(.xen_orchestra.yaml).'
+  - Uses a configuration file as an inventory source, it must end in C(.xen_orchestra.yml) or C(.xen_orchestra.yaml).
 extends_documentation_fragment:
   - constructed
   - inventory_cache
 options:
   plugin:
-            description: The name of this plugin, it should always be set to V(community.general.xen_orchestra) for this plugin to recognize it as its own.
+    description: The name of this plugin, it should always be set to V(community.general.xen_orchestra) for this plugin to
+      recognize it as its own.
     required: true
     choices: ['community.general.xen_orchestra']
     type: str
   api_host:
     description:
       - API host to XOA API.
-                - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_HOST) will be used instead.
+      - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_HOST)
+        will be used instead.
     type: str
     env:
       - name: ANSIBLE_XO_HOST
   user:
     description:
       - Xen Orchestra user.
-                - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_USER) will be used instead.
+      - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_USER)
+        will be used instead.
     required: true
     type: str
     env:
@@ -44,7 +47,8 @@ DOCUMENTATION = '''
   password:
     description:
       - Xen Orchestra password.
-                - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_PASSWORD) will be used instead.
+      - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_PASSWORD)
+        will be used instead.
     required: true
     type: str
     env:
@@ -54,7 +58,7 @@ DOCUMENTATION = '''
     type: boolean
     default: true
   use_ssl:
-            description: Use wss when connecting to the Xen Orchestra API
+    description: Use wss when connecting to the Xen Orchestra API.
     type: boolean
     default: true
   use_vm_uuid:
@@ -71,10 +75,11 @@ DOCUMENTATION = '''
     type: boolean
     default: true
     version_added: 10.4.0
-'''
+"""
 
 
-EXAMPLES = '''
+EXAMPLES = r"""
+---
 # file must be named xen_orchestra.yaml or xen_orchestra.yml
 plugin: community.general.xen_orchestra
 api_host: 192.168.1.255
@@ -88,8 +93,7 @@ compose:
   ansible_port: 2222
 use_vm_uuid: false
 use_host_uuid: true
-
+"""
-'''
 
 import json
 import ssl

plugins/lookup/bitwarden.py

@@ -5,7 +5,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = """
+DOCUMENTATION = r"""
 name: bitwarden
 author:
   - Jonathan Lung (@lungj) <lungj@heresjono.com>
@@ -27,8 +27,7 @@ DOCUMENTATION = """
   search:
     description:
       - Field to retrieve, for example V(name) or V(id).
-          - If set to V(id), only zero or one element can be returned.
+      - If set to V(id), only zero or one element can be returned. Use the Jinja C(first) filter to get the only list element.
-            Use the Jinja C(first) filter to get the only list element.
       - If set to V(None) or V(''), or if O(_terms) is empty, records are not filtered by fields.
     type: str
     default: name
@@ -58,13 +57,13 @@ DOCUMENTATION = """
     version_added: 8.4.0
   result_count:
     description:
-          - Number of results expected for the lookup query. Task will fail if O(result_count)
+      - Number of results expected for the lookup query. Task will fail if O(result_count) is set but does not match the number
-            is set but does not match the number of query results. Leave empty to skip this check.
+        of query results. Leave empty to skip this check.
     type: int
     version_added: 10.4.0
 """
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: "Get 'password' from all Bitwarden records named 'a_test'"
   ansible.builtin.debug:
     msg: >-
@@ -111,12 +110,12 @@ EXAMPLES = """
       {{ lookup('community.general.bitwarden', 'a_test', result_count=1) }}
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
   description:
     - A one-element list that contains a list of requested fields or JSON objects of matches.
-      - If you use C(query), you get a list of lists. If you use C(lookup) without C(wantlist=true),
+    - If you use C(query), you get a list of lists. If you use C(lookup) without C(wantlist=true), this always gets reduced
-        this always gets reduced to a list of field values or JSON objects.
+      to a list of field values or JSON objects.
   type: list
   elements: list
 """

plugins/lookup/bitwarden_secrets_manager.py

@@ -6,7 +6,7 @@ from __future__ import (absolute_import, division, print_function)
 
 __metaclass__ = type
 
-DOCUMENTATION = """
+DOCUMENTATION = r"""
 name: bitwarden_secrets_manager
 author:
   - jantari (@jantari)
@@ -30,7 +30,7 @@ DOCUMENTATION = """
     type: str
 """
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: Get a secret relying on the BWS_ACCESS_TOKEN environment variable for authentication
   ansible.builtin.debug:
     msg: >-
@@ -62,7 +62,7 @@ EXAMPLES = """
       {{ lookup("community.general.bitwarden_secrets_manager", "2bc23e48-4932-40de-a047-5524b7ddc972").value }}
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
   description: List containing one or more secrets.
   type: list

plugins/lookup/cartesian.py

@@ -6,24 +6,24 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: cartesian
 short_description: returns the cartesian product of lists
 description:
   - Takes the input lists and returns a list that represents the product of the input lists.
   - It is clearer with an example, it turns [1, 2, 3], [a, b] into [1, a], [1, b], [2, a], [2, b], [3, a], [3, b].
-         You can see the exact syntax in the examples section.
+  - You can see the exact syntax in the examples section.
 options:
   _terms:
     description:
-          - a set of lists
+      - A set of lists.
     type: list
     elements: list
     required: true
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: Example of the change in the description
   ansible.builtin.debug:
     msg: "{{ lookup('community.general.cartesian', [1,2,3], [a, b])}}"
@@ -37,10 +37,10 @@ EXAMPLES = """
     - [1, 2, 3, 4, 5, 6]
 """
 
-RETURN = """
+RETURN = r"""
 _list:
   description:
-      - list of lists composed of elements of the input lists
+    - List of lists composed of elements of the input lists.
   type: list
   elements: list
 """

plugins/lookup/chef_databag.py

@@ -6,37 +6,36 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: chef_databag
 short_description: fetches data from a Chef Databag
 description:
-       - "This is a lookup plugin to provide access to chef data bags using the pychef package.
+  - 'This is a lookup plugin to provide access to chef data bags using the pychef package. It interfaces with the chef server
-         It interfaces with the chef server api using the same methods to find a knife or chef-client config file to load parameters from,
+    API using the same methods to find a knife or chef-client config file to load parameters from, starting from either the
-         starting from either the given base path or the current working directory.
+    given base path or the current working directory. The lookup order mirrors the one from Chef, all folders in the base
-         The lookup order mirrors the one from Chef, all folders in the base path are walked back looking for the following configuration
+    path are walked back looking for the following configuration file in order: C(.chef/knife.rb), C(~/.chef/knife.rb), C(/etc/chef/client.rb).'
-         file in order : .chef/knife.rb, ~/.chef/knife.rb, /etc/chef/client.rb"
 requirements:
   - "pychef (L(Python library, https://pychef.readthedocs.io), C(pip install pychef))"
 options:
   name:
     description:
-            - Name of the databag
+      - Name of the databag.
     type: string
     required: true
   item:
     description:
-            - Item to fetch
+      - Item to fetch.
     type: string
     required: true
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 - ansible.builtin.debug:
     msg: "{{ lookup('community.general.chef_databag', 'name=data_bag_name item=data_bag_item') }}"
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
   description:
     - The value from the databag.

plugins/lookup/collection_version.py

@@ -5,18 +5,17 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = """
+DOCUMENTATION = r"""
 name: collection_version
 author: Felix Fontein (@felixfontein)
 version_added: "4.0.0"
 short_description: Retrieves the version of an installed collection
 description:
-  - This lookup allows to query the version of an installed collection, and to determine whether a
+  - This lookup allows to query the version of an installed collection, and to determine whether a collection is installed
-    collection is installed at all.
+    at all.
-  - By default it returns V(none) for non-existing collections and V(*) for collections without a
+  - By default it returns V(none) for non-existing collections and V(*) for collections without a version number. The latter
-    version number. The latter should only happen in development environments, or when installing
+    should only happen in development environments, or when installing a collection from git which has no version in its C(galaxy.yml).
-    a collection from git which has no version in its C(galaxy.yml). This behavior can be adjusted
+    This behavior can be adjusted by providing other values with O(result_not_found) and O(result_no_version).
-    by providing other values with O(result_not_found) and O(result_no_version).
 options:
   _terms:
     description:
@@ -34,28 +33,25 @@ options:
   result_no_version:
     description:
       - The value to return when the collection has no version number.
-      - This can happen for collections installed from git which do not have a version number
+      - This can happen for collections installed from git which do not have a version number in C(galaxy.yml).
-        in C(galaxy.yml).
       - By default, V(*) is returned.
     type: string
     default: '*'
 """
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: Check version of community.general
   ansible.builtin.debug:
     msg: "community.general version {{ lookup('community.general.collection_version', 'community.general') }}"
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
   description:
     - The version number of the collections listed as input.
-      - If a collection can not be found, it will return the value provided in O(result_not_found).
+    - If a collection can not be found, it will return the value provided in O(result_not_found). By default, this is V(none).
-        By default, this is V(none).
+    - If a collection can be found, but the version not identified, it will return the value provided in O(result_no_version).
-      - If a collection can be found, but the version not identified, it will return the value provided in
+      By default, this is V(*). This can happen for collections installed from git which do not have a version number in V(galaxy.yml).
-        O(result_no_version). By default, this is V(*). This can happen for collections installed
-        from git which do not have a version number in V(galaxy.yml).
   type: list
   elements: str
 """

plugins/lookup/consul_kv.py

@@ -7,14 +7,14 @@ from __future__ import (absolute_import, division, print_function)
 
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: consul_kv
-    short_description: Fetch metadata from a Consul key value store.
+short_description: Fetch metadata from a Consul key value store
 description:
-      - Lookup metadata for a playbook from the key value store in a Consul cluster.
+  - Lookup metadata for a playbook from the key value store in a Consul cluster. Values can be easily set in the kv store
-        Values can be easily set in the kv store with simple rest commands
+    with simple rest commands.
-      - C(curl -X PUT -d 'some-value' http://localhost:8500/v1/kv/ansible/somedata)
+  - C(curl -X PUT -d 'some-value' http://localhost:8500/v1/kv/ansible/somedata).
 requirements:
   - 'python-consul python library U(https://python-consul.readthedocs.io/en/latest/#installation)'
 options:
@@ -78,7 +78,7 @@ DOCUMENTATION = '''
   url:
     description:
       - The target to connect to.
-          - "Should look like this: V(https://my.consul.server:8500)."
+      - 'Should look like this: V(https://my.consul.server:8500).'
     type: str
     version_added: 1.0.0
     env:
@@ -86,9 +86,9 @@ DOCUMENTATION = '''
     ini:
       - section: lookup_consul
         key: url
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 - ansible.builtin.debug:
     msg: 'key contains {{item}}'
   with_community.general.consul_kv:
@@ -105,7 +105,7 @@ EXAMPLES = """
     msg: "{{ lookup('community.general.consul_kv', 'my/key', host='10.10.10.10', port=2000) }}"
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
   description:
     - Value(s) stored in consul.

plugins/lookup/credstash.py

@@ -6,54 +6,54 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: credstash
 short_description: retrieve secrets from Credstash on AWS
 requirements:
   - credstash (python library)
 description:
-      - "Credstash is a small utility for managing secrets using AWS's KMS and DynamoDB: https://github.com/fugue/credstash"
+  - "Credstash is a small utility for managing secrets using AWS's KMS and DynamoDB: https://github.com/fugue/credstash."
 options:
   _terms:
-        description: term or list of terms to lookup in the credit store
+    description: Term or list of terms to lookup in the credit store.
     type: list
     elements: string
     required: true
   table:
-        description: name of the credstash table to query
+    description: Name of the credstash table to query.
     type: str
     default: 'credential-store'
   version:
-        description: Credstash version
+    description: Credstash version.
     type: str
     default: ''
   region:
-        description: AWS region
+    description: AWS region.
     type: str
   profile_name:
-        description: AWS profile to use for authentication
+    description: AWS profile to use for authentication.
     type: str
     env:
       - name: AWS_PROFILE
   aws_access_key_id:
-        description: AWS access key ID
+    description: AWS access key ID.
     type: str
     env:
       - name: AWS_ACCESS_KEY_ID
   aws_secret_access_key:
-        description: AWS access key
+    description: AWS access key.
     type: str
     env:
       - name: AWS_SECRET_ACCESS_KEY
   aws_session_token:
-        description: AWS session token
+    description: AWS session token.
     type: str
     env:
       - name: AWS_SESSION_TOKEN
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: first use credstash to store your secrets
   ansible.builtin.shell: credstash put my-github-password secure123
 
@@ -86,7 +86,7 @@ EXAMPLES = """
         msg: "{{ lookup('community.general.credstash', 'some-password', context=dict(app='my_app', environment='production')) }}"
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
   description:
     - Value(s) stored in Credstash.

plugins/lookup/cyberarkpassword.py

@@ -6,7 +6,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: cyberarkpassword
 short_description: get secrets from CyberArk AIM
@@ -32,16 +32,18 @@ DOCUMENTATION = '''
   output:
     description:
       - Specifies the desired output fields separated by commas.
-          - "They could be: Password, PassProps.<property>, PasswordChangeInProcess"
+      - 'They could be: Password, PassProps.<property>, PasswordChangeInProcess.'
     type: string
     default: 'password'
   _extra:
-        description: for extra_params values please check parameters for clipasswordsdk in CyberArk's "Credential Provider and ASCP Implementation Guide"
+    description: For extra_params values please check parameters for clipasswordsdk in CyberArk's "Credential Provider and
+      ASCP Implementation Guide".
 notes:
-      - For Ansible on Windows, please change the -parameters (-p, -d, and -o) to /parameters (/p, /d, and /o) and change the location of CLIPasswordSDK.exe.
+  - For Ansible on Windows, please change the -parameters (C(-p), C(-d), and C(-o)) to /parameters (C(/p), C(/d), and C(/o)) and change the
-'''
+    location of C(CLIPasswordSDK.exe).
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: passing options to the lookup
   ansible.builtin.debug:
     msg: '{{ lookup("community.general.cyberarkpassword", cyquery) }}'
@@ -61,7 +63,7 @@ EXAMPLES = """
     output: 'Password,PassProps.UserName,PassProps.Address,PasswordChangeInProcess'
 """
 
-RETURN = """
+RETURN = r"""
 _result:
   description: A list containing one dictionary.
   type: list
@@ -69,12 +71,12 @@ _result:
   contains:
     password:
       description:
-        - The actual value stored
+        - The actual value stored.
     passprops:
-      description: properties assigned to the entry
+      description: Properties assigned to the entry.
       type: dictionary
     passwordchangeinprocess:
-      description: did the password change?
+      description: Did the password change?
 """
 
 import os

plugins/lookup/dependent.py

@@ -6,31 +6,30 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = """
+DOCUMENTATION = r"""
 name: dependent
 short_description: Composes a list with nested elements of other lists or dicts which can depend on previous loop variables
 author: Felix Fontein (@felixfontein)
 version_added: 3.1.0
 description:
-  - "Takes the input lists and returns a list with elements that are lists, dictionaries,
+  - Takes the input lists and returns a list with elements that are lists, dictionaries, or template expressions which evaluate
-     or template expressions which evaluate to lists or dicts, composed of the elements of
+    to lists or dicts, composed of the elements of the input evaluated lists and dictionaries.
-     the input evaluated lists and dictionaries."
 options:
   _terms:
     description:
-      - A list where the elements are one-element dictionaries, mapping a name to a string, list, or dictionary.
+      - A list where the elements are one-element dictionaries, mapping a name to a string, list, or dictionary. The name
-        The name is the index that is used in the result object. The value is iterated over as described below.
+        is the index that is used in the result object. The value is iterated over as described below.
       - If the value is a list, it is simply iterated over.
-      - If the value is a dictionary, it is iterated over and returned as if they would be processed by the
+      - If the value is a dictionary, it is iterated over and returned as if they would be processed by the P(ansible.builtin.dict2items#filter)
-        P(ansible.builtin.dict2items#filter) filter.
+        filter.
-      - If the value is a string, it is evaluated as Jinja2 expressions which can access the previously chosen
+      - If the value is a string, it is evaluated as Jinja2 expressions which can access the previously chosen elements with
-        elements with C(item.<index_name>). The result must be a list or a dictionary.
+        C(item.<index_name>). The result must be a list or a dictionary.
     type: list
     elements: dict
     required: true
 """
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: Install/remove public keys for active admin users
   ansible.posix.authorized_key:
     user: "{{ item.admin.key }}"
@@ -106,7 +105,7 @@ EXAMPLES = """
               - 5.6.7.8
 """
 
-RETURN = """
+RETURN = r"""
 _list:
   description:
     - A list composed of dictionaries whose keys are the variable names from the input list.

plugins/lookup/dig.py

@@ -6,26 +6,27 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: dig
 author: Jan-Piet Mens (@jpmens) <jpmens(at)gmail.com>
 short_description: query DNS using the dnspython library
 requirements:
   - dnspython (python library, http://www.dnspython.org/)
 description:
-      - The dig lookup runs queries against DNS servers to retrieve DNS records for a specific name (FQDN - fully qualified domain name).
+  - The dig lookup runs queries against DNS servers to retrieve DNS records for a specific name (FQDN - fully qualified domain
-        It is possible to lookup any DNS record in this manner.
+    name). It is possible to lookup any DNS record in this manner.
   - There is a couple of different syntaxes that can be used to specify what record should be retrieved, and for which name.
     It is also possible to explicitly specify the DNS server(s) to use for lookups.
-      - In its simplest form, the dig lookup plugin can be used to retrieve an IPv4 address (DNS A record) associated with FQDN
+  - In its simplest form, the dig lookup plugin can be used to retrieve an IPv4 address (DNS A record) associated with FQDN.
-      - In addition to (default) A record, it is also possible to specify a different record type that should be queried.
+  - In addition to (default) A record, it is also possible to specify a different record type that should be queried. This
-        This can be done by either passing-in additional parameter of format qtype=TYPE to the dig lookup, or by appending /TYPE to the FQDN being queried.
+    can be done by either passing-in additional parameter of format qtype=TYPE to the dig lookup, or by appending /TYPE to
-      - If multiple values are associated with the requested record, the results will be returned as a comma-separated list.
+    the FQDN being queried.
-        In such cases you may want to pass option C(wantlist=true) to the lookup call, or alternatively use C(query) instead of C(lookup),
+  - If multiple values are associated with the requested record, the results will be returned as a comma-separated list. In
+    such cases you may want to pass option C(wantlist=true) to the lookup call, or alternatively use C(query) instead of C(lookup),
     which will result in the record values being returned as a list over which you can iterate later on.
-      - By default, the lookup will rely on system-wide configured DNS servers for performing the query.
+  - By default, the lookup will rely on system-wide configured DNS servers for performing the query. It is also possible to
-        It is also possible to explicitly specify DNS servers to query using the @DNS_SERVER_1,DNS_SERVER_2,...,DNS_SERVER_N notation.
+    explicitly specify DNS servers to query using the @DNS_SERVER_1,DNS_SERVER_2,...,DNS_SERVER_N notation. This needs to
-        This needs to be passed-in as an additional parameter to the lookup
+    be passed-in as an additional parameter to the lookup.
 options:
   _terms:
     description: Domain(s) to query.
@@ -38,7 +39,8 @@ DOCUMENTATION = '''
       - V(CAA) has been added in community.general 6.3.0.
     type: str
     default: 'A'
-        choices: [A, ALL, AAAA, CAA, CNAME, DNAME, DNSKEY, DS, HINFO, LOC, MX, NAPTR, NS, NSEC3PARAM, PTR, RP, RRSIG, SOA, SPF, SRV, SSHFP, TLSA, TXT]
+    choices: [A, ALL, AAAA, CAA, CNAME, DNAME, DNSKEY, DS, HINFO, LOC, MX, NAPTR, NS, NSEC3PARAM, PTR, RP, RRSIG, SOA, SPF,
+      SRV, SSHFP, TLSA, TXT]
   flat:
     description: If 0 each record is returned as a dictionary, otherwise a string.
     type: int
@@ -51,9 +53,8 @@ DOCUMENTATION = '''
   fail_on_error:
     description:
       - Abort execution on lookup errors.
-          - The default for this option will likely change to V(true) in the future.
+      - The default for this option will likely change to V(true) in the future. The current default, V(false), is used for
-            The current default, V(false), is used for backwards compatibility, and will result in empty strings
+        backwards compatibility, and will result in empty strings or the string V(NXDOMAIN) in the result in case of errors.
-            or the string V(NXDOMAIN) in the result in case of errors.
     default: false
     type: bool
     version_added: 5.4.0
@@ -67,7 +68,7 @@ DOCUMENTATION = '''
     version_added: 6.0.0
   class:
     description:
-          - "Class."
+      - Class.
     type: str
     default: 'IN'
   tcp:
@@ -81,14 +82,16 @@ DOCUMENTATION = '''
     type: int
     version_added: 9.5.0
 notes:
-      - ALL is not a record per-se, merely the listed fields are available for any record results you retrieve in the form of a dictionary.
+  - V(ALL) is not a record in itself, merely the listed fields are available for any record results you retrieve in the form of
-      - While the 'dig' lookup plugin supports anything which dnspython supports out of the box, only a subset can be converted into a dictionary.
+    a dictionary.
-      - If you need to obtain the AAAA record (IPv6 address), you must specify the record type explicitly.
+  - While the plugin supports anything which C(dnspython) supports out of the box, only a subset can be converted
-        Syntax for specifying the record type is shown in the examples below.
+    into a dictionary.
+  - If you need to obtain the AAAA record (IPv6 address), you must specify the record type explicitly. Syntax for specifying
+    the record type is shown in the examples below.
   - The trailing dot in most of the examples listed is purely optional, but is specified for completeness/correctness sake.
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: Simple A record (IPV4 address) lookup for example.com
   ansible.builtin.debug:
     msg: "{{ lookup('community.general.dig', 'example.com.')}}"
@@ -139,83 +142,83 @@ EXAMPLES = """
     msg: "{{ lookup('community.general.dig', 'example.org./A', retry_servfail=true) }}"
 """
 
-RETURN = """
+RETURN = r"""
 _list:
   description:
-      - List of composed strings or dictionaries with key and value
+    - List of composed strings or of dictionaries, with fields depending
-        If a dictionary, fields shows the keys returned depending on query type
+      on query type.
   type: list
   elements: raw
   contains:
     ALL:
       description:
-               - owner, ttl, type
+        - C(owner), C(ttl), C(type).
     A:
       description:
-               - address
+        - C(address).
     AAAA:
       description:
-               - address
+        - C(address).
     CAA:
       description:
-               - flags
+        - C(flags).
-               - tag
+        - C(tag).
-               - value
+        - C(value).
       version_added: 6.3.0
     CNAME:
       description:
-               - target
+        - C(target).
     DNAME:
       description:
-               - target
+        - C(target).
     DNSKEY:
       description:
-                - flags, algorithm, protocol, key
+        - C(flags), C(algorithm), C(protocol), C(key).
     DS:
       description:
-                - algorithm, digest_type, key_tag, digest
+        - C(algorithm), C(digest_type), C(key_tag), C(digest).
     HINFO:
       description:
-                -  cpu, os
+        - C(cpu), C(os).
     LOC:
       description:
-                - latitude, longitude, altitude, size, horizontal_precision, vertical_precision
+        - C(latitude), C(longitude), C(altitude), C(size), C(horizontal_precision), C(vertical_precision).
     MX:
       description:
-                - preference, exchange
+        - C(preference), C(exchange).
     NAPTR:
       description:
-                - order, preference, flags, service, regexp, replacement
+        - C(order), C(preference), C(flags), C(service), C(regexp), C(replacement).
     NS:
       description:
-                - target
+        - C(target).
     NSEC3PARAM:
       description:
-                - algorithm, flags, iterations, salt
+        - C(algorithm), C(flags), C(iterations), C(salt).
     PTR:
       description:
-                - target
+        - C(target).
     RP:
       description:
-                - mbox, txt
+        - C(mbox), C(txt).
     SOA:
       description:
-                - mname, rname, serial, refresh, retry, expire, minimum
+        - C(mname), C(rname), C(serial), C(refresh), C(retry), C(expire), C(minimum).
     SPF:
       description:
-                - strings
+        - C(strings).
     SRV:
       description:
-                - priority, weight, port, target
+        - C(priority), C(weight), C(port), C(target).
     SSHFP:
       description:
-                - algorithm, fp_type, fingerprint
+        - C(algorithm), C(fp_type), C(fingerprint).
     TLSA:
       description:
-                - usage, selector, mtype, cert
+        - C(usage), C(selector), C(mtype), C(cert).
     TXT:
       description:
-                - strings
+        - C(strings).
 """
 
 from ansible.errors import AnsibleError

plugins/lookup/dnstxt.py

@@ -6,7 +6,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: dnstxt
 author: Jan-Piet Mens (@jpmens) <jpmens(at)gmail.com>
 short_description: query a domain(s)'s DNS txt fields
@@ -16,7 +16,7 @@ DOCUMENTATION = '''
   - Uses a python library to return the DNS TXT record for a domain.
 options:
   _terms:
-        description: domain or list of domains to query TXT records from
+    description: Domain or list of domains to query TXT records from.
     required: true
     type: list
     elements: string
@@ -27,9 +27,9 @@ DOCUMENTATION = '''
     default: false
     type: bool
     version_added: 6.0.0
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: show txt entry
   ansible.builtin.debug:
     msg: "{{lookup('community.general.dnstxt', ['test.example.com'])}}"
@@ -48,10 +48,10 @@ EXAMPLES = """
   with_community.general.dnstxt: "{{lookup('community.general.dnstxt', ['test.example.com']).split(',')}}"
 """
 
-RETURN = """
+RETURN = r"""
 _list:
   description:
-      - values returned by the DNS TXT record.
+    - Values returned by the DNS TXT record.
   type: list
 """
 

plugins/lookup/dsv.py

@@ -12,8 +12,7 @@ author: Adam Migus (@amigus) <adam@migus.org>
 short_description: Get secrets from Thycotic DevOps Secrets Vault
 version_added: 1.0.0
 description:
-    - Uses the Thycotic DevOps Secrets Vault Python SDK to get Secrets from a
+  - Uses the Thycotic DevOps Secrets Vault Python SDK to get Secrets from a DSV O(tenant) using a O(client_id) and O(client_secret).
-      DSV O(tenant) using a O(client_id) and O(client_secret).
 requirements:
   - python-dsv-sdk - https://pypi.org/project/python-dsv-sdk/
 options:
@@ -31,8 +30,7 @@ options:
     required: true
   tld:
     default: com
-        description: The top-level domain of the tenant; the second format
+    description: The top-level domain of the tenant; the second format parameter in the default O(url_template).
-            parameter in the default O(url_template).
     type: string
     env:
       - name: DSV_TLD
@@ -60,8 +58,7 @@ options:
     required: true
   url_template:
     default: https://{}.secretsvaultcloud.{}/v1
-        description: The path to prepend to the base URL to form a valid REST
+    description: The path to prepend to the base URL to form a valid REST API request.
-            API request.
     type: string
     env:
       - name: DSV_URL_TEMPLATE

plugins/lookup/etcd.py

@@ -8,46 +8,46 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author:
   - Jan-Piet Mens (@jpmens)
 name: etcd
 short_description: get info from an etcd server
 description:
-        - Retrieves data from an etcd server
+  - Retrieves data from an etcd server.
 options:
   _terms:
     description:
-                - the list of keys to lookup on the etcd server
+      - The list of keys to lookup on the etcd server.
     type: list
     elements: string
     required: true
   url:
     description:
-                - Environment variable with the URL for the etcd server
+      - Environment variable with the URL for the etcd server.
     type: string
     default: 'http://127.0.0.1:4001'
     env:
       - name: ANSIBLE_ETCD_URL
   version:
     description:
-                - Environment variable with the etcd protocol version
+      - Environment variable with the etcd protocol version.
     type: string
     default: 'v1'
     env:
       - name: ANSIBLE_ETCD_VERSION
   validate_certs:
     description:
-                - toggle checking that the ssl certificates are valid, you normally only want to turn this off with self-signed certs.
+      - Toggle checking that the ssl certificates are valid, you normally only want to turn this off with self-signed certs.
     default: true
     type: boolean
 seealso:
   - module: community.general.etcd3
   - plugin: community.general.etcd3
     plugin_type: lookup
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: "a value from a locally running etcd"
   ansible.builtin.debug:
     msg: "{{ lookup('community.general.etcd', 'foo/bar') }}"
@@ -59,15 +59,15 @@ EXAMPLES = '''
 - name: "you can set server options inline"
   ansible.builtin.debug:
     msg: "{{ lookup('community.general.etcd', 'foo', version='v2', url='http://192.168.0.27:4001') }}"
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
 _raw:
   description:
     - List of values associated with input keys.
   type: list
   elements: string
-'''
+"""
 
 import json
 

plugins/lookup/etcd3.py

@@ -7,7 +7,7 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author:
   - Eric Belhomme (@eric-belhomme) <ebelhomme@fr.scc.com>
 version_added: '0.2.0'
@@ -15,9 +15,9 @@ DOCUMENTATION = '''
 short_description: Get key values from etcd3 server
 description:
   - Retrieves key values and/or key prefixes from etcd3 server using its native gRPC API.
-    - Try to reuse M(community.general.etcd3) options for connection parameters, but add support for some C(ETCDCTL_*) environment variables.
+  - Try to reuse M(community.general.etcd3) options for connection parameters, but add support for some E(ETCDCTL_*) environment
+    variables.
   - See U(https://github.com/etcd-io/etcd/tree/master/Documentation/op-guide) for etcd overview.
-
 options:
   _terms:
     description:
@@ -32,8 +32,8 @@ DOCUMENTATION = '''
     default: false
   endpoints:
     description:
-            - Counterpart of E(ETCDCTL_ENDPOINTS) environment variable.
+      - Counterpart of E(ETCDCTL_ENDPOINTS) environment variable. Specify the etcd3 connection with an URL form, for example
-              Specify the etcd3 connection with and URL form, for example V(https://hostname:2379), or V(<host>:<port>) form.
+        V(https://hostname:2379), or V(<host>:<port>) form.
       - The V(host) part is overwritten by O(host) option, if defined.
       - The V(port) part is overwritten by O(port) option, if defined.
     env:
@@ -42,29 +42,29 @@ DOCUMENTATION = '''
     type: str
   host:
     description:
-            - etcd3 listening client host.
+      - Etcd3 listening client host.
       - Takes precedence over O(endpoints).
     type: str
   port:
     description:
-            - etcd3 listening client port.
+      - Etcd3 listening client port.
       - Takes precedence over O(endpoints).
     type: int
   ca_cert:
     description:
-            - etcd3 CA authority.
+      - Etcd3 CA authority.
     env:
       - name: ETCDCTL_CACERT
     type: str
   cert_cert:
     description:
-            - etcd3 client certificate.
+      - Etcd3 client certificate.
     env:
       - name: ETCDCTL_CERT
     type: str
   cert_key:
     description:
-            - etcd3 client private key.
+      - Etcd3 client private key.
     env:
       - name: ETCDCTL_KEY
     type: str
@@ -90,8 +90,8 @@ DOCUMENTATION = '''
 
 notes:
   - O(host) and O(port) options take precedence over (endpoints) option.
-    - The recommended way to connect to etcd3 server is using E(ETCDCTL_ENDPOINT)
+  - The recommended way to connect to etcd3 server is using E(ETCDCTL_ENDPOINT) environment variable and keep O(endpoints),
-      environment variable and keep O(endpoints), O(host), and O(port) unused.
+    O(host), and O(port) unused.
 seealso:
   - module: community.general.etcd3
   - plugin: community.general.etcd
@@ -99,9 +99,9 @@ DOCUMENTATION = '''
 
 requirements:
   - "etcd3 >= 0.10"
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: "a value from a locally running etcd"
   ansible.builtin.debug:
     msg: "{{ lookup('community.general.etcd3', 'foo/bar') }}"
@@ -117,9 +117,9 @@ EXAMPLES = '''
 - name: "connect to etcd3 with a client certificate"
   ansible.builtin.debug:
     msg: "{{ lookup('community.general.etcd3', 'foo/bar', cert_cert='/etc/ssl/etcd/client.pem', cert_key='/etc/ssl/etcd/client.key') }}"
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
 _raw:
   description:
     - List of keys and associated values.
@@ -132,7 +132,7 @@ RETURN = '''
     value:
       description: The element's value.
       type: str
-'''
+"""
 
 import re
 

plugins/lookup/filetree.py

@@ -6,22 +6,23 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 name: filetree
 author: Dag Wieers (@dagwieers) <dag@wieers.com>
 short_description: recursively match all files in a directory tree
 description:
   - This lookup enables you to template a complete tree of files on a target system while retaining permissions and ownership.
   - Supports directories, files and symlinks, including SELinux and other file properties.
-- If you provide more than one path, it will implement a first_found logic, and will not process entries it already processed in previous paths.
+  - If you provide more than one path, it will implement a first_found logic, and will not process entries it already processed
-  This enables merging different trees in order of importance, or add role_vars to specific paths to influence different instances of the same role.
+    in previous paths. This enables merging different trees in order of importance, or add role_vars to specific paths to
+    influence different instances of the same role.
 options:
   _terms:
     description: Path(s) of files to read.
     required: true
     type: list
     elements: string
-'''
+"""
 
 EXAMPLES = r"""
 - name: Create directories
@@ -79,7 +80,7 @@ RETURN = r"""
       description: The permissions the resulting file or directory.
       type: str
     state:
-          description: TODO
+      description: TODO.
       type: str
     owner:
       description: Name of the user that owns the file/directory.

plugins/lookup/flattened.py

@@ -6,7 +6,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: flattened
 author: Serge van Ginderachter (!UNKNOWN) <serge@vanginderachter.be>
 short_description: return single list completely flattened
@@ -14,26 +14,26 @@ DOCUMENTATION = '''
   - Given one or more lists, this lookup will flatten any list elements found recursively until only 1 list is left.
 options:
   _terms:
-        description: lists to flatten
+    description: Lists to flatten.
     type: list
     elements: raw
     required: true
 notes:
-      - Unlike the P(ansible.builtin.items#lookup) lookup which only flattens 1 level,
+  - Unlike the P(ansible.builtin.items#lookup) lookup which only flattens 1 level, this plugin will continue to flatten until
-        this plugin will continue to flatten until it cannot find lists anymore.
+    it cannot find lists anymore.
   - Aka highlander plugin, there can only be one (list).
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: "'unnest' all elements into single list"
   ansible.builtin.debug:
     msg: "all in one list {{lookup('community.general.flattened', [1,2,3,[5,6]], ['a','b','c'], [[5,6,1,3], [34,'a','b','c']])}}"
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
   description:
-      - flattened list
+    - Flattened list.
   type: list
 """
 from ansible.errors import AnsibleError

plugins/lookup/github_app_access_token.py

@@ -5,7 +5,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: github_app_access_token
 author:
   - Poh Wei Sheng (@weisheng-p)
@@ -29,7 +29,7 @@ DOCUMENTATION = '''
   installation_id:
     description:
       - The installation ID that contains the git repository you would like access to.
-        - As of 2023-12-24, this can be found via Settings page > Integrations > Application. The last part of the URL in the
+      - As of 2023-12-24, this can be found at Settings page > Integrations > Application. The last part of the URL in the
         configure button is the installation ID.
       - Alternatively, you can use PyGithub (U(https://github.com/PyGithub/PyGithub)) to get your installation ID.
     required: true
@@ -45,9 +45,9 @@ DOCUMENTATION = '''
       - How long the token should last for in seconds.
     default: 600
     type: int
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Get access token to be used for git checkout with app_id=123456, installation_id=64209
   ansible.builtin.git:
     repo: >-
@@ -57,14 +57,14 @@ EXAMPLES = '''
     github_token: >-
       {{ lookup('community.general.github_app_access_token', key_path='/home/to_your/key',
                 app_id='123456', installation_id='64209') }}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
 _raw:
   description: A one-element list containing your GitHub access token.
   type: list
   elements: str
-'''
+"""
 
 
 try:

plugins/lookup/hiera.py

@@ -6,7 +6,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author:
   - Juan Manuel Parrilla (@jparrill)
 name: hiera
@@ -37,9 +37,9 @@ DOCUMENTATION = '''
     env:
       - name: ANSIBLE_HIERA_CFG
 # FIXME: incomplete options .. _terms? environment/fqdn?
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 # All this examples depends on hiera.yml that describes the hierarchy
 
 - name: "a value from Hiera 'DB'"
@@ -55,10 +55,10 @@ EXAMPLES = """
     msg: "{{ lookup('community.general.hiera', 'foo fqdn=puppet01.localdomain') }}"
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
   description:
-            - a value associated with input key
+    - A value associated with input key.
   type: list
   elements: str
 """

plugins/lookup/keyring.py

@@ -7,7 +7,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: keyring
 author:
   - Samuel Boucher (!UNKNOWN) <boucher.samuel.c@gmail.com>
@@ -16,9 +16,9 @@ DOCUMENTATION = '''
 short_description: grab secrets from the OS keyring
 description:
   - Allows you to access data stored in the OS provided keyring/keychain.
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: output secrets to screen (BAD IDEA)
   ansible.builtin.debug:
     msg: "Password: {{item}}"
@@ -31,7 +31,7 @@ EXAMPLES = """
     login_user: joe
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
   description: Secrets stored.
   type: list

plugins/lookup/lastpass.py

@@ -6,7 +6,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: lastpass
 author:
   - Andrew Zenk (!UNKNOWN) <azenk@umn.edu>
@@ -26,17 +26,17 @@ DOCUMENTATION = '''
     description: Field to return from LastPass.
     default: 'password'
     type: str
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: get 'custom_field' from LastPass entry 'entry-name'
   ansible.builtin.debug:
     msg: "{{ lookup('community.general.lastpass', 'entry-name', field='custom_field') }}"
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
-    description: secrets stored
+  description: Secrets stored.
   type: list
   elements: str
 """

plugins/lookup/lmdb_kv.py

@@ -6,7 +6,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: lmdb_kv
 author:
   - Jan-Piet Mens (@jpmens)
@@ -27,9 +27,9 @@ DOCUMENTATION = '''
     default: 'ansible.mdb'
     vars:
       - name: lmdb_kv_db
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: query LMDB for a list of country codes
   ansible.builtin.debug:
     msg: "{{ query('community.general.lmdb_kv', 'nl', 'be', 'lu', db='jp.mdb') }}"
@@ -52,9 +52,9 @@ EXAMPLES = """
     - be
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
-  description: value(s) stored in LMDB
+  description: Value(s) stored in LMDB.
   type: list
   elements: raw
 """

plugins/lookup/merge_variables.py

@@ -6,7 +6,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = """
+DOCUMENTATION = r"""
 author:
   - Roy Lenferink (@rlenferink)
   - Mark Ettema (@m-a-r-k-e)
@@ -14,14 +14,14 @@ DOCUMENTATION = """
 name: merge_variables
 short_description: merge variables whose names match a given pattern
 description:
-        - This lookup returns the merged result of all variables in scope that match the given prefixes, suffixes, or
+  - This lookup returns the merged result of all variables in scope that match the given prefixes, suffixes, or regular expressions,
-          regular expressions, optionally.
+    optionally.
 version_added: 6.5.0
 options:
   _terms:
     description:
-          - Depending on the value of O(pattern_type), this is a list of prefixes, suffixes, or regular expressions
+      - Depending on the value of O(pattern_type), this is a list of prefixes, suffixes, or regular expressions that will
-            that will be used to match all variables that should be merged.
+        be used to match all variables that should be merged.
     required: true
     type: list
     elements: str
@@ -47,10 +47,9 @@ DOCUMENTATION = """
     description:
       - Return an error, print a warning or ignore it when a key will be overwritten.
       - The default behavior V(error) makes the plugin fail when a key would be overwritten.
-          - When V(warn) and V(ignore) are used, note that it is important to know that the variables
+      - When V(warn) and V(ignore) are used, note that it is important to know that the variables are sorted by name before
-            are sorted by name before being merged. Keys for later variables in this order will overwrite
+        being merged. Keys for later variables in this order will overwrite keys of the same name for variables earlier in
-            keys of the same name for variables earlier in this order. To avoid potential confusion,
+        this order. To avoid potential confusion, better use O(override=error) whenever possible.
-            better use O(override=error) whenever possible.
     type: str
     default: 'error'
     choices:
@@ -64,14 +63,14 @@ DOCUMENTATION = """
         key: override
   groups:
     description:
-          - Search for variables accross hosts that belong to the given groups. This allows to collect configuration pieces
+      - Search for variables across hosts that belong to the given groups. This allows to collect configuration pieces across
-            accross different hosts (for example a service on a host with its database on another host).
+        different hosts (for example a service on a host with its database on another host).
     type: list
     elements: str
     version_added: 8.5.0
 """
 
-EXAMPLES = """
+EXAMPLES = r"""
 # Some example variables, they can be defined anywhere as long as they are in scope
 test_init_list:
   - "list init item 1"
@@ -91,7 +90,6 @@ testb__test_dict:
   ports:
     - 3
 
-
 # Merge variables that end with '__test_dict' and store the result in a variable 'example_a'
 example_a: "{{ lookup('community.general.merge_variables', '__test_dict', pattern_type='suffix') }}"
 
@@ -100,7 +98,6 @@ example_a: "{{ lookup('community.general.merge_variables', '__test_dict', patter
 #   - 1
 #   - 3
 
-
 # Merge variables that match the '^.+__test_list$' regular expression, starting with an initial value and store the
 # result in a variable 'example_b'
 example_b: "{{ lookup('community.general.merge_variables', '^.+__test_list$', initial_value=test_init_list) }}"
@@ -112,10 +109,10 @@ example_b: "{{ lookup('community.general.merge_variables', '^.+__test_list$', in
 #   - "test b item 1"
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
-    description: In case the search matches list items, a list will be returned. In case the search matches dicts, a
+  description: In case the search matches list items, a list will be returned. In case the search matches dicts, a dict will
-     dict will be returned.
+    be returned.
   type: raw
   elements: raw
 """

plugins/lookup/onepassword.py

@@ -8,7 +8,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: onepassword
 author:
   - Scott Buchanan (@scottsb)
@@ -38,9 +38,10 @@ DOCUMENTATION = '''
 extends_documentation_fragment:
   - community.general.onepassword
   - community.general.onepassword.lookup
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
+---
 # These examples only work when already signed in to 1Password
 - name: Retrieve password for KITT when already signed in to 1Password
   ansible.builtin.debug:
@@ -56,28 +57,20 @@ EXAMPLES = """
 
 - name: Retrieve password for HAL when not signed in to 1Password
   ansible.builtin.debug:
-    var: lookup('community.general.onepassword',
+    var: lookup('community.general.onepassword', 'HAL 9000', subdomain='Discovery', master_password=vault_master_password)
-                'HAL 9000',
-                subdomain='Discovery',
-                master_password=vault_master_password)
 
 - name: Retrieve password for HAL when never signed in to 1Password
   ansible.builtin.debug:
-    var: lookup('community.general.onepassword',
+    var: >-
-                'HAL 9000',
+      lookup('community.general.onepassword', 'HAL 9000', subdomain='Discovery', master_password=vault_master_password,
-                subdomain='Discovery',
+             username='tweety@acme.com', secret_key=vault_secret_key)
-                master_password=vault_master_password,
-                username='tweety@acme.com',
-                secret_key=vault_secret_key)
 
 - name: Retrieve password from specific account
   ansible.builtin.debug:
-    var: lookup('community.general.onepassword',
+    var: lookup('community.general.onepassword', 'HAL 9000', account_id='abc123')
-                'HAL 9000',
-                account_id='abc123')
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
   description: Field data requested.
   type: list

plugins/lookup/onepassword_doc.py

@@ -6,7 +6,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: onepassword_doc
 author:
   - Sam Doran (@samdoran)
@@ -19,7 +19,6 @@ DOCUMENTATION = '''
 notes:
   - The document contents are a string exactly as stored in 1Password.
   - This plugin requires C(op) version 2 or later.
-
 options:
   _terms:
     description: Identifier(s) (case-insensitive UUID or name) of item(s) to retrieve.
@@ -30,17 +29,18 @@ DOCUMENTATION = '''
 extends_documentation_fragment:
   - community.general.onepassword
   - community.general.onepassword.lookup
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
+---
 - name: Retrieve a private key from 1Password
   ansible.builtin.debug:
     var: lookup('community.general.onepassword_doc', 'Private key')
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
-    description: Requested document
+  description: Requested document.
   type: list
   elements: string
 """

plugins/lookup/onepassword_raw.py

@@ -8,7 +8,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: onepassword_raw
 author:
   - Scott Buchanan (@scottsb)
@@ -34,9 +34,10 @@ DOCUMENTATION = '''
 extends_documentation_fragment:
   - community.general.onepassword
   - community.general.onepassword.lookup
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
+---
 - name: Retrieve all data about Wintermute
   ansible.builtin.debug:
     var: lookup('community.general.onepassword_raw', 'Wintermute')
@@ -46,7 +47,7 @@ EXAMPLES = """
     var: lookup('community.general.onepassword_raw', 'Wintermute', subdomain='Turing', vault_password='DmbslfLvasjdl')
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
   description: Entire item requested.
   type: list

plugins/lookup/onepassword_ssh_key.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = """
+DOCUMENTATION = r"""
 name: onepassword_ssh_key
 author:
   - Mohammed Babelly (@mohammedbabelly20)
@@ -19,7 +19,6 @@ notes:
   - By default, it returns the private key value in PKCS#8 format, unless O(ssh_format=true) is passed.
   - The pluging works only for C(SSHKEY) type items.
   - This plugin requires C(op) version 2 or later.
-
 options:
   _terms:
     description: Identifier(s) (case-insensitive UUID or name) of item(s) to retrieve.
@@ -36,13 +35,14 @@ extends_documentation_fragment:
   - community.general.onepassword.lookup
 """
 
-EXAMPLES = """
+EXAMPLES = r"""
+---
 - name: Retrieve the private SSH key from 1Password
   ansible.builtin.debug:
     msg: "{{ lookup('community.general.onepassword_ssh_key', 'SSH Key', ssh_format=true) }}"
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
   description: Private key of SSH keypair.
   type: list

plugins/lookup/passwordstore.py

@@ -7,26 +7,26 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: passwordstore
 author:
   - Patrick Deelman (!UNKNOWN) <patrick@patrickdeelman.nl>
 short_description: manage passwords with passwordstore.org's pass utility
 description:
-      - Enables Ansible to retrieve, create or update passwords from the passwordstore.org pass utility.
+  - Enables Ansible to retrieve, create or update passwords from the passwordstore.org pass utility. It can also retrieve,
-        It can also retrieve, create or update YAML style keys stored as multilines in the passwordfile.
+    create or update YAML style keys stored as multilines in the passwordfile.
-      - To avoid problems when accessing multiple secrets at once, add C(auto-expand-secmem) to
+  - To avoid problems when accessing multiple secrets at once, add C(auto-expand-secmem) to C(~/.gnupg/gpg-agent.conf). Where
-        C(~/.gnupg/gpg-agent.conf). Where this is not possible, consider using O(lock=readwrite) instead.
+    this is not possible, consider using O(lock=readwrite) instead.
 options:
   _terms:
-        description: query key.
+    description: Query key.
     required: true
   directory:
     description:
       - The directory of the password store.
       - If O(backend=pass), the default is V(~/.password-store) is used.
-          - If O(backend=gopass), then the default is the C(path) field in C(~/.config/gopass/config.yml),
+      - If O(backend=gopass), then the default is the C(path) field in C(~/.config/gopass/config.yml), falling back to V(~/.local/share/gopass/stores/root)
-            falling back to V(~/.local/share/gopass/stores/root) if C(path) is not defined in the gopass config.
+        if C(path) is not defined in the gopass config.
     type: path
     vars:
       - name: passwordstore
@@ -79,8 +79,8 @@ DOCUMENTATION = '''
       - If O(create=true), the value for this option is ignored and assumed to be V(create).
       - If set to V(error), the lookup will error out if the passname does not exist.
       - If set to V(create), the passname will be created with the provided length O(length) if it does not exist.
-          - If set to V(empty) or V(warn), will return a V(none) in case the passname does not exist.
+      - If set to V(empty) or V(warn), will return a V(none) in case the passname does not exist. When using C(lookup) and
-            When using C(lookup) and not C(query), this will be translated to an empty string.
+        not C(query), this will be translated to an empty string.
     version_added: 3.1.0
     type: str
     default: error
@@ -108,7 +108,8 @@ DOCUMENTATION = '''
   locktimeout:
     description:
       - Lock timeout applied when O(lock) is not V(none).
-          - Time with a unit suffix, V(s), V(m), V(h) for seconds, minutes, and hours, respectively. For example, V(900s) equals V(15m).
+      - Time with a unit suffix, V(s), V(m), V(h) for seconds, minutes, and hours, respectively. For example, V(900s) equals
+        V(15m).
       - Correlates with C(pinentry-timeout) in C(~/.gnupg/gpg-agent.conf), see C(man gpg-agent) for details.
     ini:
       - section: passwordstore_lookup
@@ -159,15 +160,15 @@ DOCUMENTATION = '''
         key: missing_subkey
 notes:
   - The lookup supports passing all options as lookup parameters since community.general 6.0.0.
-'''
+"""
-EXAMPLES = """
+EXAMPLES = r"""
 ansible.cfg: |
   [passwordstore_lookup]
   lock=readwrite
   locktimeout=45s
   missing_subkey=warn
 
-tasks.yml: |
+tasks.yml: |-
   ---
 
   # Debug is used for examples, BAD IDEA to show passwords on screen
@@ -233,10 +234,10 @@ tasks.yml: |
       passfilecontent: "{{ lookup('community.general.passwordstore', 'example/test', returnall=true)}}"
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
   description:
-    - a password
+    - A password.
   type: list
   elements: str
 """

plugins/lookup/random_pet.py

@@ -8,7 +8,7 @@ from __future__ import (absolute_import, division, print_function)
 
 __metaclass__ = type
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 name: random_pet
 author:
   - Abhijeet Kasurde (@Akasurde)
@@ -37,9 +37,9 @@ DOCUMENTATION = r'''
     description: The character to separate words in the pet name.
     default: "-"
     type: str
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Generate pet name
   ansible.builtin.debug:
     var: lookup('community.general.random_pet')
@@ -59,14 +59,14 @@ EXAMPLES = r'''
   ansible.builtin.debug:
     var: lookup('community.general.random_pet', length=7)
   # Example result: 'natural-peacock'
-'''
+"""
 
-RETURN = r'''
+RETURN = r"""
 _raw:
-    description: A one-element list containing a random pet name
+  description: A one-element list containing a random pet name.
   type: list
   elements: str
-'''
+"""
 
 try:
     import petname

plugins/lookup/random_string.py

@@ -16,8 +16,8 @@ DOCUMENTATION = r"""
 version_added: '3.2.0'
 description:
   - Generates random string based upon the given constraints.
-      - Uses L(random.SystemRandom,https://docs.python.org/3/library/random.html#random.SystemRandom),
+  - Uses L(random.SystemRandom,https://docs.python.org/3/library/random.html#random.SystemRandom), so should be strong enough
-        so should be strong enough for cryptographic purposes.
+    for cryptographic purposes.
 options:
   length:
     description: The length of the string.
@@ -77,8 +77,7 @@ DOCUMENTATION = r"""
     type: str
   override_all:
     description:
-        - Override all values of O(numbers), O(upper), O(lower), and O(special) with
+      - Override all values of O(numbers), O(upper), O(lower), and O(special) with the given list of characters.
-          the given list of characters.
     type: str
   ignore_similar_chars:
     description:
@@ -143,7 +142,7 @@ EXAMPLES = r"""
 
 RETURN = r"""
 _raw:
-    description: A one-element list containing a random string
+  description: A one-element list containing a random string.
   type: list
   elements: str
 """

plugins/lookup/random_words.py

@@ -18,8 +18,7 @@ DOCUMENTATION = r"""
 requirements:
   - xkcdpass U(https://github.com/redacted/XKCD-password-generator)
 description:
-      - Returns a number of random words. The output can for example be used for
+  - Returns a number of random words. The output can for example be used for passwords.
-        passwords.
   - See U(https://xkcd.com/936/) for background.
 options:
   numwords:

plugins/lookup/redis.py

@@ -6,23 +6,23 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: redis
 author:
   - Jan-Piet Mens (@jpmens) <jpmens(at)gmail.com>
   - Ansible Core Team
 short_description: fetch data from Redis
 description:
-      - This lookup returns a list of results from a Redis DB corresponding to a list of items given to it
+  - This lookup returns a list of results from a Redis DB corresponding to a list of items given to it.
 requirements:
   - redis (python library https://github.com/andymccurdy/redis-py/)
 options:
   _terms:
-        description: list of keys to query
+    description: List of keys to query.
     type: list
     elements: string
   host:
-        description: location of Redis host
+    description: Location of Redis host.
     type: string
     default: '127.0.0.1'
     env:
@@ -31,7 +31,7 @@ DOCUMENTATION = '''
       - section: lookup_redis
         key: host
   port:
-        description: port on which Redis is listening on
+    description: Port on which Redis is listening on.
     default: 6379
     type: int
     env:
@@ -40,16 +40,16 @@ DOCUMENTATION = '''
       - section: lookup_redis
         key: port
   socket:
-        description: path to socket on which to query Redis, this option overrides host and port options when set.
+    description: Path to socket on which to query Redis, this option overrides host and port options when set.
     type: path
     env:
       - name: ANSIBLE_REDIS_SOCKET
     ini:
       - section: lookup_redis
         key: socket
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 - name: query redis for somekey (default or configured settings used)
   ansible.builtin.debug:
     msg: "{{ lookup('community.general.redis', 'somekey') }}"
@@ -66,12 +66,11 @@ EXAMPLES = """
 - name: use list directly with a socket
   ansible.builtin.debug:
     msg: "{{ lookup('community.general.redis', 'key1', 'key2', socket='/var/tmp/redis.sock') }}"
-
 """
 
-RETURN = """
+RETURN = r"""
 _raw:
-  description: value(s) stored in Redis
+  description: Value(s) stored in Redis.
   type: list
   elements: str
 """

plugins/lookup/revbitspss.py

@@ -12,8 +12,8 @@ author: RevBits (@RevBits) <info@revbits.com>
 short_description: Get secrets from RevBits PAM server
 version_added: 4.1.0
 description:
-    - Uses the revbits_ansible Python SDK to get Secrets from RevBits PAM
+  - Uses the revbits_ansible Python SDK to get Secrets from RevBits PAM Server using API key authentication with the REST
-      Server using API key authentication with the REST API.
+    API.
 requirements:
   - revbits_ansible - U(https://pypi.org/project/revbits_ansible/)
 options:
@@ -45,6 +45,7 @@ _list:
 """
 
 EXAMPLES = r"""
+---
 - hosts: localhost
   vars:
     secret: >-
@@ -58,7 +59,7 @@ EXAMPLES = r"""
       }}
   tasks:
     - ansible.builtin.debug:
-          msg: >
+        msg: >-
           UUIDPAM is {{ (secret['UUIDPAM']) }} and DB_PASS is {{ (secret['DB_PASS']) }}
 """
 

plugins/lookup/shelvefile.py

@@ -6,7 +6,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: shelvefile
 author: Alejandro Guirao (!UNKNOWN) <lekumberri@gmail.com>
 short_description: read keys from Python shelve file
@@ -25,15 +25,16 @@ DOCUMENTATION = '''
     description: Path to shelve file.
     type: path
     required: true
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
+---
 - name: Retrieve a string value corresponding to a key inside a Python shelve file
   ansible.builtin.debug:
     msg: "{{ lookup('community.general.shelvefile', 'file=path_to_some_shelve_file.db key=key_to_retrieve') }}"
 """
 
-RETURN = """
+RETURN = r"""
 _list:
   description: Value(s) of key(s) in shelve file(s).
   type: list

plugins/lookup/tss.py

@@ -12,12 +12,10 @@ author: Adam Migus (@amigus) <adam@migus.org>
 short_description: Get secrets from Thycotic Secret Server
 version_added: 1.0.0
 description:
-    - Uses the Thycotic Secret Server Python SDK to get Secrets from Secret
+  - Uses the Thycotic Secret Server Python SDK to get Secrets from Secret Server using token authentication with O(username)
-      Server using token authentication with O(username) and O(password) on
+    and O(password) on the REST API at O(base_url).
-      the REST API at O(base_url).
+  - When using self-signed certificates the environment variable E(REQUESTS_CA_BUNDLE) can be set to a file containing the
-    - When using self-signed certificates the environment variable
+    trusted certificates (in C(.pem) format).
-      E(REQUESTS_CA_BUNDLE) can be set to a file containing the trusted certificates
-      (in C(.pem) format).
   - For example, C(export REQUESTS_CA_BUNDLE='/etc/ssl/certs/ca-bundle.trust.crt').
 requirements:
   - python-tss-sdk - https://pypi.org/project/python-tss-sdk/
@@ -34,7 +32,7 @@ options:
     version_added: 7.2.0
   fetch_secret_ids_from_folder:
     description:
-            - Boolean flag which indicates whether secret ids are in a folder is fetched by folder ID or not.
+      - Boolean flag which indicates whether secret IDs are in a folder is fetched by folder ID or not.
       - V(true) then the terms will be considered as a folder IDs. Otherwise (default), they are considered as secret IDs.
     required: false
     type: bool
@@ -106,16 +104,14 @@ options:
     version_added: 3.7.0
   api_path_uri:
     default: /api/v1
-        description: The path to append to the base URL to form a valid REST
+    description: The path to append to the base URL to form a valid REST API request.
-            API request.
     type: string
     env:
       - name: TSS_API_PATH_URI
     required: false
   token_path_uri:
     default: /oauth2/token
-        description: The path to append to the base URL to form a valid OAuth2
+    description: The path to append to the base URL to form a valid OAuth2 Access Grant request.
-            Access Grant request.
     type: string
     env:
       - name: TSS_TOKEN_PATH_URI
@@ -251,7 +247,7 @@ EXAMPLES = r"""
       }}
   tasks:
     - ansible.builtin.debug:
-          msg: >
+        msg: >-
           the password is {{
             (secret['items']
               | items2dict(key_name='slug',