Adjust YAML in plugin docs (#10234)

* Adjust YAML in plugin docs.

* Update ignore.txt.

* Forgot two indents.

* adjust connection plugins
adjust filter plugins
adjust inventory plugins
adjust lookup plugins

* Re-add YAML document start.

---------

Co-authored-by: Alexei Znamensky <russoz@gmail.com>

plugins/connection/wsl.py

@@ -99,7 +99,7 @@ options:
         section: paramiko_connection
     type: boolean
   look_for_keys:
-    default: True
+    default: true
     description: "Set to V(false) to disable searching for private key files in C(~/.ssh/)."
     env:
       - name: ANSIBLE_PARAMIKO_LOOK_FOR_KEYS
@@ -119,7 +119,7 @@ options:
     vars:
       - name: ansible_paramiko_proxy_command
   record_host_keys:
-    default: True
+    default: true
     description: "Save the host keys to a file."
     env:
       - name: ANSIBLE_PARAMIKO_RECORD_HOST_KEYS
@@ -147,7 +147,7 @@ options:
   use_persistent_connections:
     description: "Toggles the use of persistence for connections."
     type: boolean
-    default: False
+    default: false
     env:
       - name: ANSIBLE_USE_PERSISTENT_CONNECTIONS
     ini:

plugins/filter/to_prettytable.py

@@ -5,7 +5,7 @@
 
 from __future__ import (absolute_import, division, print_function)
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: to_prettytable
 short_description: Format a list of dictionaries as an ASCII table
 version_added: "10.7.0"
@@ -37,9 +37,9 @@ options:
           For example, V({'name': 'left', 'id': 'right'}) will align the C(name) column to the left
           and the C(id) column to the right.
     type: dictionary
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 ---
 - name: Set a list of users
   ansible.builtin.set_fact:
@@ -104,13 +104,13 @@ EXAMPLES = '''
           column_alignments={'name': 'center', 'age': 'right', 'role': 'left'}
         )
       }}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
 _value:
   description: The formatted ASCII table.
   type: string
-'''
+"""
 
 try:
     import prettytable

plugins/inventory/cobbler.py

@@ -5,7 +5,7 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Orion Poplawski (@opoplawski)
 name: cobbler
 short_description: Cobbler inventory source
@@ -117,15 +117,15 @@ DOCUMENTATION = '''
     choices: ['normal', 'as_rendered']
     default: normal
     version_added: 10.7.0
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 # my.cobbler.yml
 plugin: community.general.cobbler
 url: http://cobbler/cobbler_api
 user: ansible-tester
 password: secure
-'''
+"""
 
 import socket
 

plugins/inventory/gitlab_runners.py

@@ -7,7 +7,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: gitlab_runners
 author:
   - Stefan Heitmüller (@morph027) <stefan.heitmueller@gmx.com>
@@ -54,9 +54,9 @@ DOCUMENTATION = '''
     description: Toggle to (not) include all available nodes metadata
     type: bool
     default: true
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 ---
 # gitlab_runners.yml
 plugin: community.general.gitlab_runners
@@ -79,7 +79,7 @@ keyed_groups:
   # hint: labels containing special characters will be converted to safe names
   - key: 'tag_list'
     prefix: tag
-'''
+"""
 
 from ansible.errors import AnsibleError, AnsibleParserError
 from ansible.plugins.inventory import BaseInventoryPlugin, Constructable

plugins/inventory/icinga2.py

@@ -6,7 +6,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: icinga2
 short_description: Icinga2 inventory source
 version_added: 3.7.0
@@ -68,9 +68,9 @@ DOCUMENTATION = '''
     type: boolean
     default: true
     version_added: 8.4.0
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 # my.icinga2.yml
 plugin: community.general.icinga2
 url: http://localhost:5665
@@ -93,7 +93,7 @@ compose:
   # set 'ansible_user' and 'ansible_port' from icinga2 host vars
   ansible_user: icinga2_attributes.vars.ansible_user
   ansible_port: icinga2_attributes.vars.ansible_port | default(22)
-'''
+"""
 
 import json
 

plugins/inventory/iocage.py

@@ -6,7 +6,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 name: iocage
 short_description: iocage inventory source
 version_added: 10.2.0
@@ -110,9 +110,9 @@ notes:
     expects to find the O(hooks_results) items in the path
     C(/iocage/iocage/jails/<name>/root). If you mount the C(poolname) to a
     different path the easiest remedy is to create a symlink.
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 ---
 # file name must end with iocage.yaml or iocage.yml
 plugin: community.general.iocage
@@ -182,7 +182,7 @@ compose:
   ansible_host: iocage_hooks.0
 groups:
   test: inventory_hostname.startswith('test')
-'''
+"""
 
 import re
 import os

plugins/inventory/linode.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 name: linode
 author:
   - Luke Murphy (@decentral1se)
@@ -75,9 +75,9 @@ DOCUMENTATION = r'''
     version_added: 2.0.0
   keyed_groups:
     version_added: 2.0.0
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 ---
 # Minimal example. `LINODE_ACCESS_TOKEN` is exposed in environment.
 plugin: community.general.linode
@@ -124,7 +124,7 @@ access_token: foobar
 ip_style: api
 compose:
   ansible_host: "ipv4 | community.general.json_query('[?public==`false`].address') | first"
-'''
+"""
 
 from ansible.errors import AnsibleError
 from ansible.plugins.inventory import BaseInventoryPlugin, Constructable, Cacheable

plugins/inventory/lxd.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 name: lxd
 short_description: Returns Ansible inventory from lxd host
 description:
@@ -104,9 +104,9 @@ DOCUMENTATION = r'''
       - Create groups by the following keywords C(location), C(network_range), C(os), C(pattern), C(profile), C(release), C(type), C(vlanid).
       - See example for syntax.
     type: dict
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 ---
 # simple lxd.yml
 plugin: community.general.lxd
@@ -165,7 +165,7 @@ groupby:
   projectInternals:
     type: project
     attribute: internals
-'''
+"""
 
 import json
 import re

plugins/inventory/nmap.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: nmap
 short_description: Uses nmap to find hosts to target
@@ -99,8 +99,8 @@ DOCUMENTATION = '''
 notes:
   - At least one of O(ipv4) or O(ipv6) is required to be V(true); both can be V(true), but they cannot both be V(false).
   - 'TODO: add OS fingerprinting'
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
 ---
 # inventory.config file in YAML format
 plugin: community.general.nmap
@@ -122,7 +122,7 @@ exclude: 192.168.0.1, web.example.com
 port: 22, 443
 groups:
   web_servers: "ports | selectattr('port', 'equalto', '443')"
-'''
+"""
 
 import os
 import re

plugins/inventory/online.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 name: online
 author:
   - Remy Leone (@remyleone)
@@ -45,9 +45,9 @@ DOCUMENTATION = r'''
       - location
       - offer
       - rpn
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 # online_inventory.yml file in YAML format
 # Example command line: ansible-inventory --list -i online_inventory.yml
 
@@ -58,7 +58,7 @@ groups:
   - location
   - offer
   - rpn
-'''
+"""
 
 import json
 from sys import version as python_version

plugins/inventory/opennebula.py

@@ -6,7 +6,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 name: opennebula
 author:
   - Kristian Feldsam (@feldsam)
@@ -74,9 +74,9 @@ DOCUMENTATION = r'''
     description: Create host groups by vm labels
     type: bool
     default: true
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 # inventory_opennebula.yml file in YAML format
 # Example command line: ansible-inventory --list -i inventory_opennebula.yml
 
@@ -84,7 +84,7 @@ EXAMPLES = r'''
 plugin: community.general.opennebula
 api_url: https://opennebula:2633/RPC2
 filter_by_label: Cache
-'''
+"""
 
 try:
     import pyone

plugins/inventory/scaleway.py

@@ -6,7 +6,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 name: scaleway
 author:
   - Remy Leone (@remyleone)
@@ -70,9 +70,9 @@ DOCUMENTATION = r'''
                   L(Scaleway API, https://developer.scaleway.com/#servers-server-get)
                   can be used.'
     type: dict
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 # scaleway_inventory.yml file in YAML format
 # Example command line: ansible-inventory --list -i scaleway_inventory.yml
 
@@ -110,7 +110,7 @@ variables:
   ansible_host: public_ip.address
   ansible_connection: "'ssh'"
   ansible_user: "'admin'"
-'''
+"""
 
 import os
 import json

plugins/inventory/virtualbox.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: virtualbox
 short_description: virtualbox inventory source
@@ -52,9 +52,9 @@ DOCUMENTATION = '''
     default: false
     type: bool
     version_added: 9.2.0
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 ---
 # file must be named vbox.yaml or vbox.yml
 plugin: community.general.virtualbox
@@ -69,7 +69,7 @@ compose:
 plugin: community.general.virtualbox
 groups:
   container: "'minis' in (inventory_hostname)"
-'''
+"""
 
 import os
 

plugins/lookup/dig.py

@@ -39,8 +39,30 @@ options:
       - 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,
+    choices:
-      SRV, SSHFP, TLSA, TXT]
+      - 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

plugins/test/ansible_type.py

@@ -27,10 +27,10 @@ DOCUMENTATION = '''
 '''
 
 EXAMPLES = '''
-
 # Substitution converts str to AnsibleUnicode or _AnsibleTaggedStr
 # ----------------------------------------------------------------
 
+---
 # String. AnsibleUnicode or _AnsibleTaggedStr.
 dtype:
   - AnsibleUnicode
@@ -39,6 +39,7 @@ data: "abc"
 result: '{{ data is community.general.ansible_type(dtype) }}'
 # result => true
 
+---
 # String. AnsibleUnicode/_AnsibleTaggedStr alias str.
 alias: {"AnsibleUnicode": "str", "_AnsibleTaggedStr": "str"}
 dtype: str
@@ -46,6 +47,7 @@ data: "abc"
 result: '{{ data is community.general.ansible_type(dtype, alias) }}'
 # result => true
 
+---
 # List. All items are AnsibleUnicode/_AnsibleTaggedStr.
 dtype:
   - list[AnsibleUnicode]
@@ -54,6 +56,7 @@ data: ["a", "b", "c"]
 result: '{{ data is community.general.ansible_type(dtype) }}'
 # result => true
 
+---
 # Dictionary. All keys and values are AnsibleUnicode/_AnsibleTaggedStr.
 dtype:
   - dict[AnsibleUnicode, AnsibleUnicode]
@@ -65,41 +68,49 @@ result: '{{ data is community.general.ansible_type(dtype) }}'
 # No substitution and no alias. Type of strings is str
 # ----------------------------------------------------
 
+---
 # String
 dtype: str
 result: '{{ "abc" is community.general.ansible_type(dtype) }}'
 # result => true
 
+---
 # Integer
 dtype: int
 result: '{{ 123 is community.general.ansible_type(dtype) }}'
 # result => true
 
+---
 # Float
 dtype: float
 result: '{{ 123.45 is community.general.ansible_type(dtype) }}'
 # result => true
 
+---
 # Boolean
 dtype: bool
 result: '{{ true is community.general.ansible_type(dtype) }}'
 # result => true
 
+---
 # List. All items are strings.
 dtype: list[str]
 result: '{{ ["a", "b", "c"] is community.general.ansible_type(dtype) }}'
 # result => true
 
+---
 # List of dictionaries.
 dtype: list[dict]
 result: '{{ [{"a": 1}, {"b": 2}] is community.general.ansible_type(dtype) }}'
 # result => true
 
+---
 # Dictionary. All keys are strings. All values are integers.
 dtype: dict[str, int]
 result: '{{ {"a": 1} is community.general.ansible_type(dtype) }}'
 # result => true
 
+---
 # Dictionary. All keys are strings. All values are integers.
 dtype: dict[str, int]
 result: '{{ {"a": 1, "b": 2} is community.general.ansible_type(dtype) }}'
@@ -108,6 +119,7 @@ result: '{{ {"a": 1, "b": 2} is community.general.ansible_type(dtype) }}'
 # Type of strings is AnsibleUnicode, _AnsibleTaggedStr, or str
 # ------------------------------------------------------------
 
+---
 # Dictionary. The keys are integers or strings. All values are strings.
 alias:
   AnsibleUnicode: str
@@ -118,6 +130,7 @@ data: {1: 'a', 'b': 'b'}
 result: '{{ data is community.general.ansible_type(dtype, alias) }}'
 # result => true
 
+---
 # Dictionary. All keys are integers. All values are keys.
 alias:
   AnsibleUnicode: str
@@ -128,6 +141,7 @@ data: {1: 'a', 2: 'b'}
 result: '{{ data is community.general.ansible_type(dtype, alias) }}'
 # result => true
 
+---
 # Dictionary. All keys are strings. Multiple types values.
 alias:
   AnsibleUnicode: str
@@ -135,10 +149,11 @@ alias:
   _AnsibleTaggedInt: int
   _AnsibleTaggedFloat: float
 dtype: dict[str, bool|dict|float|int|list|str]
-data: {'a': 1, 'b': 1.1, 'c': 'abc', 'd': True, 'e': ['x', 'y', 'z'], 'f': {'x': 1, 'y': 2}}
+data: {'a': 1, 'b': 1.1, 'c': 'abc', 'd': true, 'e': ['x', 'y', 'z'], 'f': {'x': 1, 'y': 2}}
 result: '{{ data is community.general.ansible_type(dtype, alias) }}'
 # result => true
 
+---
 # List. Multiple types items.
 alias:
   AnsibleUnicode: str
@@ -146,25 +161,28 @@ alias:
   _AnsibleTaggedInt: int
   _AnsibleTaggedFloat: float
 dtype: list[bool|dict|float|int|list|str]
-data: [1, 2, 1.1, 'abc', True, ['x', 'y', 'z'], {'x': 1, 'y': 2}]
+data: [1, 2, 1.1, 'abc', true, ['x', 'y', 'z'], {'x': 1, 'y': 2}]
 result: '{{ data is community.general.ansible_type(dtype, alias) }}'
 # result => true
 
 # Option dtype is list
 # --------------------
 
+---
 # AnsibleUnicode, _AnsibleTaggedStr, or str
 dtype: ['AnsibleUnicode', '_AnsibleTaggedStr', 'str']
 data: abc
 result: '{{ data is community.general.ansible_type(dtype) }}'
 # result => true
 
+---
 # float or int
 dtype: ['float', 'int', "_AnsibleTaggedInt", "_AnsibleTaggedFloat"]
 data: 123
 result: '{{ data is community.general.ansible_type(dtype) }}'
 # result => true
 
+---
 # float or int
 dtype: ['float', 'int', "_AnsibleTaggedInt", "_AnsibleTaggedFloat"]
 data: 123.45
@@ -174,6 +192,7 @@ result: '{{ data is community.general.ansible_type(dtype) }}'
 # Multiple alias
 # --------------
 
+---
 # int alias number
 alias:
   int: number
@@ -185,6 +204,7 @@ data: 123
 result: '{{ data is community.general.ansible_type(dtype, alias) }}'
 # result => true
 
+---
 # float alias number
 alias:
   int: number

tests/sanity/ignore-2.15.txt

@@ -17,4 +17,5 @@ plugins/modules/parted.py validate-modules:parameter-state-invalid-choice
 plugins/modules/rhevm.py validate-modules:parameter-state-invalid-choice
 plugins/modules/udm_user.py import-3.11  # Uses deprecated stdlib library 'crypt'
 plugins/modules/xfconf.py validate-modules:return-syntax-error
+plugins/test/ansible_type.py yamllint:unparsable-with-libyaml
 tests/unit/plugins/modules/test_gio_mime.yaml no-smart-quotes

tests/sanity/ignore-2.16.txt

@@ -18,4 +18,5 @@ plugins/modules/rhevm.py validate-modules:parameter-state-invalid-choice
 plugins/modules/udm_user.py import-3.11  # Uses deprecated stdlib library 'crypt'
 plugins/modules/udm_user.py import-3.12  # Uses deprecated stdlib library 'crypt'
 plugins/modules/xfconf.py validate-modules:return-syntax-error
+plugins/test/ansible_type.py yamllint:unparsable-with-libyaml
 tests/unit/plugins/modules/test_gio_mime.yaml no-smart-quotes