[PR #9453/040cd0ca backport][stable-9] normalize docs in cache/connection plugins (#9461)

normalize docs in cache/connection plugins (#9453)

Normalize doc blocks for plugins

(cherry picked from commit 040cd0ca50)

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

plugins/connection/chroot.py

@@ -10,79 +10,66 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
-    author: Maykel Moya (!UNKNOWN) <mmoya@speedyrails.com>
-    name: chroot
-    short_description: Interact with local chroot
+DOCUMENTATION = r"""
+author: Maykel Moya (!UNKNOWN) <mmoya@speedyrails.com>
+name: chroot
+short_description: Interact with local chroot
+description:
+  - Run commands or put/fetch files to an existing chroot on the Ansible controller.
+options:
+  remote_addr:
     description:
-        - Run commands or put/fetch files to an existing chroot on the Ansible controller.
-    options:
-      remote_addr:
-        description:
-            - The path of the chroot you want to access.
-        type: string
-        default: inventory_hostname
-        vars:
-            - name: inventory_hostname
-            - name: ansible_host
-      executable:
-        description:
-            - User specified executable shell
-        type: string
-        ini:
-          - section: defaults
-            key: executable
-        env:
-          - name: ANSIBLE_EXECUTABLE
-        vars:
-          - name: ansible_executable
-        default: /bin/sh
-      chroot_exe:
-        description:
-            - User specified chroot binary
-        type: string
-        ini:
-          - section: chroot_connection
-            key: exe
-        env:
-          - name: ANSIBLE_CHROOT_EXE
-        vars:
-          - name: ansible_chroot_exe
-        default: chroot
-      disable_root_check:
-        description:
-            - Do not check that the user is not root.
-        ini:
-          - section: chroot_connection
-            key: disable_root_check
-        env:
-          - name: ANSIBLE_CHROOT_DISABLE_ROOT_CHECK
-        vars:
-          - name: ansible_chroot_disable_root_check
-        default: false
-        type: bool
-        version_added: 7.3.0
-'''
+      - The path of the chroot you want to access.
+    type: string
+    default: inventory_hostname
+    vars:
+      - name: inventory_hostname
+      - name: ansible_host
+  executable:
+    description:
+      - User specified executable shell.
+    type: string
+    ini:
+      - section: defaults
+        key: executable
+    env:
+      - name: ANSIBLE_EXECUTABLE
+    vars:
+      - name: ansible_executable
+    default: /bin/sh
+  chroot_exe:
+    description:
+      - User specified chroot binary.
+    type: string
+    ini:
+      - section: chroot_connection
+        key: exe
+    env:
+      - name: ANSIBLE_CHROOT_EXE
+    vars:
+      - name: ansible_chroot_exe
+    default: chroot
+  disable_root_check:
+    description:
+      - Do not check that the user is not root.
+    ini:
+      - section: chroot_connection
+        key: disable_root_check
+    env:
+      - name: ANSIBLE_CHROOT_DISABLE_ROOT_CHECK
+    vars:
+      - name: ansible_chroot_disable_root_check
+    default: false
+    type: bool
+    version_added: 7.3.0
+"""
 
 EXAMPLES = r"""
-# Plugin requires root privileges for chroot, -E preserves your env (and location of ~/.ansible):
-# sudo -E ansible-playbook ...
-#
-# Static inventory file
-# [chroots]
-# /path/to/debootstrap
-# /path/to/feboostrap
-# /path/to/lxc-image
-# /path/to/chroot
-
-# playbook
----
 - hosts: chroots
   connection: community.general.chroot
   tasks:
     - debug:
         msg: "This is coming from chroot environment"
-
 """
 
 import os

plugins/connection/funcd.py

@@ -9,24 +9,24 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
-    author: Michael Scherer (@mscherer) <misc@zarb.org>
-    name: funcd
-    short_description: Use funcd to connect to target
+DOCUMENTATION = r"""
+author: Michael Scherer (@mscherer) <misc@zarb.org>
+name: funcd
+short_description: Use funcd to connect to target
+description:
+  - This transport permits you to use Ansible over Func.
+  - For people who have already setup func and that wish to play with ansible, this permit to move gradually to ansible without
+    having to redo completely the setup of the network.
+options:
+  remote_addr:
     description:
-        - This transport permits you to use Ansible over Func.
-        - For people who have already setup func and that wish to play with ansible,
-          this permit to move gradually to ansible without having to redo completely the setup of the network.
-    options:
-      remote_addr:
-        description:
-            - The path of the chroot you want to access.
-        type: string
-        default: inventory_hostname
-        vars:
-            - name: ansible_host
-            - name: ansible_func_host
-'''
+      - The path of the chroot you want to access.
+    type: string
+    default: inventory_hostname
+    vars:
+      - name: ansible_host
+      - name: ansible_func_host
+"""
 
 HAVE_FUNC = False
 try:

plugins/connection/incus.py

@@ -8,47 +8,47 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = """
-    author: Stéphane Graber (@stgraber)
-    name: incus
-    short_description: Run tasks in Incus instances via the Incus CLI.
+DOCUMENTATION = r"""
+author: Stéphane Graber (@stgraber)
+name: incus
+short_description: Run tasks in Incus instances using the Incus CLI
+description:
+  - Run commands or put/fetch files to an existing Incus instance using Incus CLI.
+version_added: "8.2.0"
+options:
+  remote_addr:
     description:
-        - Run commands or put/fetch files to an existing Incus instance using Incus CLI.
-    version_added: "8.2.0"
-    options:
-      remote_addr:
-        description:
-            - The instance identifier.
-        type: string
-        default: inventory_hostname
-        vars:
-            - name: inventory_hostname
-            - name: ansible_host
-            - name: ansible_incus_host
-      executable:
-        description:
-            - The shell to use for execution inside the instance.
-        type: string
-        default: /bin/sh
-        vars:
-            - name: ansible_executable
-            - name: ansible_incus_executable
-      remote:
-        description:
-            - The name of the Incus remote to use (per C(incus remote list)).
-            - Remotes are used to access multiple servers from a single client.
-        type: string
-        default: local
-        vars:
-            - name: ansible_incus_remote
-      project:
-        description:
-            - The name of the Incus project to use (per C(incus project list)).
-            - Projects are used to divide the instances running on a server.
-        type: string
-        default: default
-        vars:
-            - name: ansible_incus_project
+      - The instance identifier.
+    type: string
+    default: inventory_hostname
+    vars:
+      - name: inventory_hostname
+      - name: ansible_host
+      - name: ansible_incus_host
+  executable:
+    description:
+      - The shell to use for execution inside the instance.
+    type: string
+    default: /bin/sh
+    vars:
+      - name: ansible_executable
+      - name: ansible_incus_executable
+  remote:
+    description:
+      - The name of the Incus remote to use (per C(incus remote list)).
+      - Remotes are used to access multiple servers from a single client.
+    type: string
+    default: local
+    vars:
+      - name: ansible_incus_remote
+  project:
+    description:
+      - The name of the Incus project to use (per C(incus project list)).
+      - Projects are used to divide the instances running on a server.
+    type: string
+    default: default
+    vars:
+      - name: ansible_incus_project
 """
 
 import os

plugins/connection/iocage.py

@@ -10,28 +10,28 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
-    author: Stephan Lohse (!UNKNOWN) <dev-github@ploek.org>
-    name: iocage
-    short_description: Run tasks in iocage jails
+DOCUMENTATION = r"""
+author: Stephan Lohse (!UNKNOWN) <dev-github@ploek.org>
+name: iocage
+short_description: Run tasks in iocage jails
+description:
+  - Run commands or put/fetch files to an existing iocage jail.
+options:
+  remote_addr:
     description:
-        - Run commands or put/fetch files to an existing iocage jail
-    options:
-      remote_addr:
-        description:
-            - Path to the jail
-        type: string
-        vars:
-            - name: ansible_host
-            - name: ansible_iocage_host
-      remote_user:
-        description:
-            - User to execute as inside the jail
-        type: string
-        vars:
-            - name: ansible_user
-            - name: ansible_iocage_user
-'''
+      - Path to the jail.
+    type: string
+    vars:
+      - name: ansible_host
+      - name: ansible_iocage_host
+  remote_user:
+    description:
+      - User to execute as inside the jail.
+    type: string
+    vars:
+      - name: ansible_user
+      - name: ansible_iocage_user
+"""
 
 import subprocess
 

plugins/connection/jail.py

@@ -10,30 +10,30 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
-    author: Ansible Core Team
-    name: jail
-    short_description: Run tasks in jails
+DOCUMENTATION = r"""
+author: Ansible Core Team
+name: jail
+short_description: Run tasks in jails
+description:
+  - Run commands or put/fetch files to an existing jail.
+options:
+  remote_addr:
     description:
-        - Run commands or put/fetch files to an existing jail
-    options:
-      remote_addr:
-        description:
-            - Path to the jail
-        type: string
-        default: inventory_hostname
-        vars:
-            - name: inventory_hostname
-            - name: ansible_host
-            - name: ansible_jail_host
-      remote_user:
-        description:
-            - User to execute as inside the jail
-        type: string
-        vars:
-            - name: ansible_user
-            - name: ansible_jail_user
-'''
+      - Path to the jail.
+    type: string
+    default: inventory_hostname
+    vars:
+      - name: inventory_hostname
+      - name: ansible_host
+      - name: ansible_jail_host
+  remote_user:
+    description:
+      - User to execute as inside the jail.
+    type: string
+    vars:
+      - name: ansible_user
+      - name: ansible_jail_user
+"""
 
 import os
 import os.path

plugins/connection/lxc.py

@@ -7,31 +7,31 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
-    author: Joerg Thalheim (!UNKNOWN) <joerg@higgsboson.tk>
-    name: lxc
-    short_description: Run tasks in lxc containers via lxc python library
+DOCUMENTATION = r"""
+author: Joerg Thalheim (!UNKNOWN) <joerg@higgsboson.tk>
+name: lxc
+short_description: Run tasks in LXC containers using lxc python library
+description:
+  - Run commands or put/fetch files to an existing LXC container using lxc python library.
+options:
+  remote_addr:
     description:
-        - Run commands or put/fetch files to an existing lxc container using lxc python library
-    options:
-      remote_addr:
-        description:
-            - Container identifier
-        type: string
-        default: inventory_hostname
-        vars:
-            - name: inventory_hostname
-            - name: ansible_host
-            - name: ansible_lxc_host
-      executable:
-        default: /bin/sh
-        description:
-            - Shell executable
-        type: string
-        vars:
-            - name: ansible_executable
-            - name: ansible_lxc_executable
-'''
+      - Container identifier.
+    type: string
+    default: inventory_hostname
+    vars:
+      - name: inventory_hostname
+      - name: ansible_host
+      - name: ansible_lxc_host
+  executable:
+    default: /bin/sh
+    description:
+      - Shell executable.
+    type: string
+    vars:
+      - name: ansible_executable
+      - name: ansible_lxc_executable
+"""
 
 import os
 import shutil

plugins/connection/lxd.py

@@ -7,48 +7,48 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
-    author: Matt Clay (@mattclay) <matt@mystile.com>
-    name: lxd
-    short_description: Run tasks in LXD instances via C(lxc) CLI
+DOCUMENTATION = r"""
+author: Matt Clay (@mattclay) <matt@mystile.com>
+name: lxd
+short_description: Run tasks in LXD instances using C(lxc) CLI
+description:
+  - Run commands or put/fetch files to an existing instance using C(lxc) CLI.
+options:
+  remote_addr:
     description:
-        - Run commands or put/fetch files to an existing instance using C(lxc) CLI.
-    options:
-      remote_addr:
-        description:
-            - Instance (container/VM) identifier.
-            - Since community.general 8.0.0, a FQDN can be provided; in that case, the first component (the part before C(.))
-              is used as the instance identifier.
-        type: string
-        default: inventory_hostname
-        vars:
-            - name: inventory_hostname
-            - name: ansible_host
-            - name: ansible_lxd_host
-      executable:
-        description:
-            - Shell to use for execution inside instance.
-        type: string
-        default: /bin/sh
-        vars:
-            - name: ansible_executable
-            - name: ansible_lxd_executable
-      remote:
-        description:
-            - Name of the LXD remote to use.
-        type: string
-        default: local
-        vars:
-            - name: ansible_lxd_remote
-        version_added: 2.0.0
-      project:
-        description:
-            - Name of the LXD project to use.
-        type: string
-        vars:
-            - name: ansible_lxd_project
-        version_added: 2.0.0
-'''
+      - Instance (container/VM) identifier.
+      - Since community.general 8.0.0, a FQDN can be provided; in that case, the first component (the part before C(.)) is
+        used as the instance identifier.
+    type: string
+    default: inventory_hostname
+    vars:
+      - name: inventory_hostname
+      - name: ansible_host
+      - name: ansible_lxd_host
+  executable:
+    description:
+      - Shell to use for execution inside instance.
+    type: string
+    default: /bin/sh
+    vars:
+      - name: ansible_executable
+      - name: ansible_lxd_executable
+  remote:
+    description:
+      - Name of the LXD remote to use.
+    type: string
+    default: local
+    vars:
+      - name: ansible_lxd_remote
+    version_added: 2.0.0
+  project:
+    description:
+      - Name of the LXD project to use.
+    type: string
+    vars:
+      - name: ansible_lxd_project
+    version_added: 2.0.0
+"""
 
 import os
 from subprocess import Popen, PIPE

plugins/connection/qubes.py

@@ -12,34 +12,33 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 
-DOCUMENTATION = '''
-    name: qubes
-    short_description: Interact with an existing QubesOS AppVM
+DOCUMENTATION = r"""
+name: qubes
+short_description: Interact with an existing QubesOS AppVM
 
+description:
+  - Run commands or put/fetch files to an existing Qubes AppVM using qubes tools.
+author: Kushal Das (@kushaldas)
+
+
+options:
+  remote_addr:
     description:
-        - Run commands or put/fetch files to an existing Qubes AppVM using qubes tools.
-
-    author: Kushal Das (@kushaldas)
-
-
-    options:
-      remote_addr:
-        description:
-            - VM name.
-        type: string
-        default: inventory_hostname
-        vars:
-            - name: ansible_host
-      remote_user:
-        description:
-            - The user to execute as inside the VM.
-        type: string
-        default: The I(user) account as default in Qubes OS.
-        vars:
-            - name: ansible_user
+      - VM name.
+    type: string
+    default: inventory_hostname
+    vars:
+      - name: ansible_host
+  remote_user:
+    description:
+      - The user to execute as inside the VM.
+    type: string
+    default: The I(user) account as default in Qubes OS.
+    vars:
+      - name: ansible_user
 #        keyword:
 #            - name: hosts
-'''
+"""
 
 import subprocess
 

plugins/connection/saltstack.py

@@ -10,13 +10,13 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
-    author: Michael Scherer (@mscherer) <misc@zarb.org>
-    name: saltstack
-    short_description: Allow ansible to piggyback on salt minions
-    description:
-        - This allows you to use existing Saltstack infrastructure to connect to targets.
-'''
+DOCUMENTATION = r"""
+author: Michael Scherer (@mscherer) <misc@zarb.org>
+name: saltstack
+short_description: Allow ansible to piggyback on salt minions
+description:
+  - This allows you to use existing Saltstack infrastructure to connect to targets.
+"""
 
 import os
 import base64

plugins/connection/zone.py

@@ -11,22 +11,22 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
-    author: Ansible Core Team
-    name: zone
-    short_description: Run tasks in a zone instance
+DOCUMENTATION = r"""
+author: Ansible Core Team
+name: zone
+short_description: Run tasks in a zone instance
+description:
+  - Run commands or put/fetch files to an existing zone.
+options:
+  remote_addr:
     description:
-        - Run commands or put/fetch files to an existing zone.
-    options:
-      remote_addr:
-        description:
-            - Zone identifier
-        type: string
-        default: inventory_hostname
-        vars:
-            - name: ansible_host
-            - name: ansible_zone_host
-'''
+      - Zone identifier.
+    type: string
+    default: inventory_hostname
+    vars:
+      - name: ansible_host
+      - name: ansible_zone_host
+"""
 
 import os
 import os.path