Reformat documentation with 'andebox yaml-doc'.

plugins/cliconf/routeros.py

@@ -5,15 +5,14 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
 author: "Egor Zaitsev (@heuels)"
 name: routeros
 short_description: Use routeros cliconf to run command on MikroTik RouterOS platform
 description:
-  - This routeros plugin provides low level abstraction apis for
-    sending and receiving CLI commands from MikroTik RouterOS network devices.
-'''
+  - This routeros plugin provides low level abstraction apis for sending and receiving CLI commands from MikroTik RouterOS
+    network devices.
+"""
 
 import re
 import json

plugins/doc_fragments/api.py

@@ -10,7 +10,7 @@
 
 class ModuleDocFragment(object):
 
-    DOCUMENTATION = r'''
+    DOCUMENTATION = r"""
 options:
   hostname:
     description:
@@ -50,21 +50,19 @@ class ModuleDocFragment(object):
     description:
       - Set to V(true) to connect without a certificate when O(tls=true).
       - See also O(validate_certs).
-      - B(Note:) this forces the use of anonymous Diffie-Hellman (ADH) ciphers. The protocol is susceptible
-        to Man-in-the-Middle attacks, because the keys used in the exchange are not authenticated.
-        Instead of simply connecting without a certificate to "make things work" have a look at
-        O(validate_certs) and O(ca_path).
+      - B(Note:) this forces the use of anonymous Diffie-Hellman (ADH) ciphers. The protocol is susceptible to Man-in-the-Middle
+        attacks, because the keys used in the exchange are not authenticated. Instead of simply connecting without a certificate
+        to "make things work" have a look at O(validate_certs) and O(ca_path).
     type: bool
     default: false
     version_added: 2.4.0
   validate_certs:
     description:
       - Set to V(false) to skip validation of TLS certificates.
       - See also O(validate_cert_hostname). Only used when O(tls=true).
-      - B(Note:) instead of simply deactivating certificate validations to "make things work",
-        please consider creating your own CA certificate and using it to sign certificates used
-        for your router. You can tell the module about your CA certificate with the O(ca_path)
-        option.
+      - B(Note:) instead of simply deactivating certificate validations to "make things work", please consider creating your
+        own CA certificate and using it to sign certificates used for your router. You can tell the module about your CA certificate
+        with the O(ca_path) option.
     type: bool
     default: true
     version_added: 1.2.0
@@ -93,10 +91,10 @@ class ModuleDocFragment(object):
   - Python >= 3.6 (for librouteros)
 seealso:
   - ref: ansible_collections.community.routeros.docsite.api-guide
-    description: How to connect to RouterOS devices with the RouterOS API
-'''
+    description: How to connect to RouterOS devices with the RouterOS API.
+"""
 
-    RESTRICT = r'''
+    RESTRICT = r"""
 options:
   restrict:
     type: list
@@ -115,24 +113,21 @@ class ModuleDocFragment(object):
       values:
         description:
           - The values of the field to limit to.
-          - >-
-            Note that the types of the values are important. If you provide a string V("0"),
-            and librouteros converts the value returned by the API to the integer V(0),
-            then this will not match. If you are not sure, better include both variants:
-            both the string and the integer.
+          - 'Note that the types of the values are important. If you provide a string V("0"), and librouteros converts the
+            value returned by the API to the integer V(0), then this will not match. If you are not sure, better include both
+            variants: both the string and the integer.'
         type: list
         elements: raw
       regex:
         description:
           - A regular expression matching values of the field to limit to.
           - Note that all values will be converted to strings before matching.
-          - It is not possible to match disabled values with regular expressions.
-            Set O(restrict[].match_disabled=true) if you also want to match disabled values.
+          - It is not possible to match disabled values with regular expressions. Set O(restrict[].match_disabled=true) if
+            you also want to match disabled values.
         type: str
       invert:
         description:
-          - Invert the condition. This affects O(restrict[].match_disabled), O(restrict[].values),
-            and O(restrict[].regex).
+          - Invert the condition. This affects O(restrict[].match_disabled), O(restrict[].values), and O(restrict[].regex).
         type: bool
         default: false
-'''
+"""

plugins/doc_fragments/attributes.py

@@ -11,17 +11,17 @@
 class ModuleDocFragment(object):
 
     # Standard documentation fragment
-    DOCUMENTATION = r'''
+    DOCUMENTATION = r"""
 options: {}
 attributes:
-    check_mode:
-      description: Can run in C(check_mode) and return changed status prediction without modifying target.
-    diff_mode:
-      description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
-    platform:
-      description: Target OS/families that can be operated against.
-      support: N/A
-'''
+  check_mode:
+    description: Can run in C(check_mode) and return changed status prediction without modifying target.
+  diff_mode:
+    description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
+  platform:
+    description: Target OS/families that can be operated against.
+    support: N/A
+"""
 
     # Should be used together with the standard fragment
     INFO_MODULE = r'''
@@ -47,23 +47,23 @@ class ModuleDocFragment(object):
         - community.routeros.api
 '''
 
-    CONN = r'''
+    CONN = r"""
 options: {}
 attributes:
-    become:
-      description: Is usable alongside C(become) keywords.
-    connection:
-      description: Uses the target's configured connection information to execute code on it.
-    delegation:
-      description: Can be used in conjunction with C(delegate_to) and related keywords.
-'''
+  become:
+    description: Is usable alongside C(become) keywords.
+  connection:
+    description: Uses the target's configured connection information to execute code on it.
+  delegation:
+    description: Can be used in conjunction with C(delegate_to) and related keywords.
+"""
 
-    FACTS = r'''
+    FACTS = r"""
 options: {}
 attributes:
-    facts:
-      description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
-'''
+  facts:
+    description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
+"""
 
     # Should be used together with the standard fragment and the FACTS fragment
     FACTS_MODULE = r'''
@@ -81,18 +81,18 @@ class ModuleDocFragment(object):
       support: full
 '''
 
-    FILES = r'''
+    FILES = r"""
 options: {}
 attributes:
-    safe_file_operations:
-      description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
-'''
+  safe_file_operations:
+    description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
+"""
 
-    FLOW = r'''
+    FLOW = r"""
 options: {}
 attributes:
-    action:
-      description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
-    async:
-      description: Supports being used with the C(async) keyword.
-'''
+  action:
+    description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
+  async:
+    description: Supports being used with the C(async) keyword.
+"""

plugins/modules/api.py

@@ -8,8 +8,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
 module: api
 author: "Nikolay Dachev (@NikolayDachev)"
 short_description: Ansible module for RouterOS API
@@ -18,9 +17,8 @@
   - This module can add, remove, update, query and execute arbitrary command in RouterOS via API.
 notes:
   - O(add), O(remove), O(update), O(cmd), and O(query) are mutually exclusive.
-  - Use the M(community.routeros.api_modify) and M(community.routeros.api_find_and_modify) modules
-    for more specific modifications, and the M(community.routeros.api_info) module for a more controlled
-    way of returning all entries for a path.
+  - Use the M(community.routeros.api_modify) and M(community.routeros.api_find_and_modify) modules for more specific modifications,
+    and the M(community.routeros.api_info) module for a more controlled way of returning all entries for a path.
 extends_documentation_fragment:
   - community.routeros.api
   - community.routeros.attributes
@@ -68,11 +66,12 @@
       - Query given path for selected query attributes from RouterOS aip.
       - WHERE is key word which extend query. WHERE format is key operator value - with spaces.
       - WHERE valid operators are V(==) or V(eq), V(!=) or V(not), V(>) or V(more), V(<) or V(less).
-      - Example path V(ip address) and query V(.id address) will return only C(.id) and C(address) for all items in V(ip address) path.
-      - Example path V(ip address) and query V(.id address WHERE address == 1.1.1.3/32).
-        will return only C(.id) and C(address) for items in V(ip address) path, where address is eq to 1.1.1.3/32.
-      - Example path V(interface) and query V(mtu name WHERE mut > 1400) will
-        return only interfaces C(mtu,name) where mtu is bigger than 1400.
+      - Example path V(ip address) and query V(.id address) will return only C(.id) and C(address) for all items in V(ip address)
+        path.
+      - Example path V(ip address) and query V(.id address WHERE address == 1.1.1.3/32). will return only C(.id) and C(address)
+        for items in V(ip address) path, where address is eq to 1.1.1.3/32.
+      - Example path V(interface) and query V(mtu name WHERE mut > 1400) will return only interfaces C(mtu,name) where mtu
+        is bigger than 1400.
       - Equivalent in RouterOS CLI C(/interface print where mtu > 1400).
     type: str
   extended_query:
@@ -91,7 +90,8 @@
       where:
         description:
           - Allows to restrict the objects returned.
-          - The conditions here must all match. An O(extended_query.where[].or) condition needs at least one of its conditions to match.
+          - The conditions here must all match. An O(extended_query.where[].or) condition needs at least one of its conditions
+            to match.
         type: list
         elements: dict
         suboptions:
@@ -105,7 +105,8 @@
             description:
               - The operator to use for matching.
               - For equality use V(==) or V(eq). For less use V(<) or V(less). For more use V(>) or V(more).
-              - Use V(in) to check whether the value is part of a list. In that case, O(extended_query.where[].value) must be a list.
+              - Use V(in) to check whether the value is part of a list. In that case, O(extended_query.where[].value) must
+                be a list.
               - Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute), O(extended_query.where[].is),
                 and O(extended_query.where[].value) have to be specified.
             type: str
@@ -133,7 +134,8 @@
                 description:
                   - The operator to use for matching.
                   - For equality use V(==) or V(eq). For less use V(<) or V(less). For more use V(>) or V(more).
-                  - Use V(in) to check whether the value is part of a list. In that case, O(extended_query.where[].or[].value) must be a list.
+                  - Use V(in) to check whether the value is part of a list. In that case, O(extended_query.where[].or[].value)
+                    must be a list.
                 type: str
                 choices: ["==", "!=", ">", "<", "in", "eq", "not", "more", "less"]
                 required: true
@@ -150,14 +152,14 @@
     type: str
 seealso:
   - ref: ansible_collections.community.routeros.docsite.quoting
-    description: How to quote and unquote commands and arguments
+    description: How to quote and unquote commands and arguments.
   - module: community.routeros.api_facts
   - module: community.routeros.api_find_and_modify
   - module: community.routeros.api_info
   - module: community.routeros.api_modify
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Get example - ip address print
   community.routeros.api:
     hostname: "{{ hostname }}"
@@ -216,8 +218,8 @@
         - attribute: "network"
           is: "in"
           value:
-             - "10.20.36.0"
-             - "192.168.255.0"
+            - "10.20.36.0"
+            - "192.168.255.0"
   register: extended_queryout
 
 - name: Dump "Extended query example" output
@@ -231,9 +233,9 @@
     username: "{{ username }}"
     path: "ip address"
     update: >-
-        .id=*14
-        address=192.168.255.20/24
-        comment={{ 'Update 192.168.255.10/24 to 192.168.255.20/24 on ether2' | community.routeros.quote_argument_value }}
+      .id=*14
+      address=192.168.255.20/24
+      comment={{ 'Update 192.168.255.10/24 to 192.168.255.20/24 on ether2' | community.routeros.quote_argument_value }}
 
 - name: Remove example - ether2 ip 192.168.255.20/24 with ".id = *14"
   community.routeros.api:
@@ -255,18 +257,17 @@
 - name: Dump "Arbitrary command example" output
   ansible.builtin.debug:
     msg: '{{ arbitraryout }}'
-'''
+"""
 
-RETURN = '''
----
+RETURN = r"""
 message:
-    description: All outputs are in list with dictionary elements returned from RouterOS api.
-    sample:
-        - address: 1.2.3.4
-        - address: 2.3.4.5
-    type: list
-    returned: always
-'''
+  description: All outputs are in list with dictionary elements returned from RouterOS api.
+  sample:
+    - address: 1.2.3.4
+    - address: 2.3.4.5
+  type: list
+  returned: always
+"""
 
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.common.text.converters import to_native