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>
2025-06-28 03:00:23 -07:00 · 2025-06-16 17:46:01 +02:00 · 2025-06-16 17:46:01 +02:00 · d032de3b16
commit d032de3b16
parent e8f965fbf8
22 changed files with 903 additions and 859 deletions
--- a/plugins/connection/wsl.py
+++ b/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:
--- a/plugins/filter/to_prettytable.py
+++ b/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
--- a/plugins/inventory/cobbler.py
+++ b/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

--- a/plugins/inventory/gitlab_runners.py
+++ b/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
--- a/plugins/inventory/icinga2.py
+++ b/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

--- a/plugins/inventory/iocage.py
+++ b/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
--- a/plugins/inventory/linode.py
+++ b/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
--- a/plugins/inventory/lxd.py
+++ b/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
--- a/plugins/inventory/nmap.py
+++ b/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
--- a/plugins/inventory/online.py
+++ b/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
--- a/plugins/inventory/opennebula.py
+++ b/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
--- a/plugins/inventory/scaleway.py
+++ b/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
--- a/plugins/inventory/virtualbox.py
+++ b/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

--- a/plugins/lookup/dig.py
+++ b/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,
-      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
--- a/plugins/test/ansible_type.py
+++ b/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
--- a/tests/sanity/ignore-2.15.txt
+++ b/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
--- a/tests/sanity/ignore-2.16.txt
+++ b/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