[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/cache/memcached.py

@@ -7,7 +7,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: memcached
 short_description: Use memcached DB for cache
@@ -18,7 +18,7 @@ DOCUMENTATION = '''
 options:
   _uri:
     description:
-          - List of connection information for the memcached DBs
+      - List of connection information for the memcached DBs.
     default: ['127.0.0.1:11211']
     type: list
     elements: string
@@ -28,7 +28,7 @@ DOCUMENTATION = '''
       - key: fact_caching_connection
         section: defaults
   _prefix:
-        description: User defined prefix to use when creating the DB entries
+    description: User defined prefix to use when creating the DB entries.
     type: string
     default: ansible_facts
     env:
@@ -40,13 +40,13 @@ DOCUMENTATION = '''
     default: 86400
     type: integer
         # TODO: determine whether it is OK to change to: type: float
-        description: Expiration timeout in seconds for the cache plugin data. Set to 0 to never expire
+    description: Expiration timeout in seconds for the cache plugin data. Set to 0 to never expire.
     env:
       - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
     ini:
       - key: fact_caching_timeout
         section: defaults
-'''
+"""
 
 import collections
 import os

plugins/cache/pickle.py

@@ -8,9 +8,9 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: pickle
-    short_description: Pickle formatted files.
+short_description: Pickle formatted files
 description:
   - This cache uses Python's pickle serialization format, in per host files, saved to the filesystem.
 author: Brian Coca (@bcoca)
@@ -18,7 +18,7 @@ DOCUMENTATION = '''
   _uri:
     required: true
     description:
-          - Path in which the cache plugin will save the files
+      - Path in which the cache plugin will save the files.
     env:
       - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
     ini:
@@ -26,7 +26,7 @@ DOCUMENTATION = '''
         section: defaults
     type: path
   _prefix:
-        description: User defined prefix to use when creating the files
+    description: User defined prefix to use when creating the files.
     env:
       - name: ANSIBLE_CACHE_PLUGIN_PREFIX
     ini:
@@ -35,14 +35,14 @@ DOCUMENTATION = '''
     type: string
   _timeout:
     default: 86400
-        description: Expiration timeout in seconds for the cache plugin data. Set to 0 to never expire
+    description: Expiration timeout in seconds for the cache plugin data. Set to 0 to never expire.
     env:
       - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
     ini:
       - key: fact_caching_timeout
         section: defaults
     type: float
-'''
+"""
 
 try:
     import cPickle as pickle

plugins/cache/redis.py

@@ -6,7 +6,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: redis
 short_description: Use Redis DB for cache
@@ -29,7 +29,7 @@ DOCUMENTATION = '''
       - key: fact_caching_connection
         section: defaults
   _prefix:
-        description: User defined prefix to use when creating the DB entries
+    description: User defined prefix to use when creating the DB entries.
     type: string
     default: ansible_facts
     env:
@@ -60,13 +60,13 @@ DOCUMENTATION = '''
     default: 86400
     type: integer
         # TODO: determine whether it is OK to change to: type: float
-        description: Expiration timeout in seconds for the cache plugin data. Set to 0 to never expire
+    description: Expiration timeout in seconds for the cache plugin data. Set to 0 to never expire.
     env:
       - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
     ini:
       - key: fact_caching_timeout
         section: defaults
-'''
+"""
 
 import re
 import time

plugins/cache/yaml.py

@@ -8,9 +8,9 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: yaml
-    short_description: YAML formatted files.
+short_description: YAML formatted files
 description:
   - This cache uses YAML formatted, per host, files saved to the filesystem.
 author: Brian Coca (@bcoca)
@@ -18,7 +18,7 @@ DOCUMENTATION = '''
   _uri:
     required: true
     description:
-          - Path in which the cache plugin will save the files
+      - Path in which the cache plugin will save the files.
     env:
       - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
     ini:
@@ -26,7 +26,7 @@ DOCUMENTATION = '''
         section: defaults
     type: string
   _prefix:
-        description: User defined prefix to use when creating the files
+    description: User defined prefix to use when creating the files.
     env:
       - name: ANSIBLE_CACHE_PLUGIN_PREFIX
     ini:
@@ -35,7 +35,7 @@ DOCUMENTATION = '''
     type: string
   _timeout:
     default: 86400
-        description: Expiration timeout in seconds for the cache plugin data. Set to 0 to never expire
+    description: Expiration timeout in seconds for the cache plugin data. Set to 0 to never expire.
     env:
       - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
     ini:
@@ -43,7 +43,7 @@ DOCUMENTATION = '''
         section: defaults
     type: integer
         # TODO: determine whether it is OK to change to: type: float
-'''
+"""
 
 
 import codecs

plugins/connection/chroot.py

@@ -10,7 +10,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Maykel Moya (!UNKNOWN) <mmoya@speedyrails.com>
 name: chroot
 short_description: Interact with local chroot
@@ -27,7 +27,7 @@ DOCUMENTATION = '''
       - name: ansible_host
   executable:
     description:
-            - User specified executable shell
+      - User specified executable shell.
     type: string
     ini:
       - section: defaults
@@ -39,7 +39,7 @@ DOCUMENTATION = '''
     default: /bin/sh
   chroot_exe:
     description:
-            - User specified chroot binary
+      - User specified chroot binary.
     type: string
     ini:
       - section: chroot_connection
@@ -62,27 +62,14 @@ DOCUMENTATION = '''
     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,14 +9,14 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+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.
+  - 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:
@@ -26,7 +26,7 @@ DOCUMENTATION = '''
     vars:
       - name: ansible_host
       - name: ansible_func_host
-'''
+"""
 
 HAVE_FUNC = False
 try:

plugins/connection/incus.py

@@ -8,10 +8,10 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = """
+DOCUMENTATION = r"""
 author: Stéphane Graber (@stgraber)
 name: incus
-    short_description: Run tasks in Incus instances via the Incus CLI.
+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"

plugins/connection/iocage.py

@@ -10,28 +10,28 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+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
+  - Run commands or put/fetch files to an existing iocage jail.
 options:
   remote_addr:
     description:
-            - Path to the jail
+      - Path to the jail.
     type: string
     vars:
       - name: ansible_host
       - name: ansible_iocage_host
   remote_user:
     description:
-            - User to execute as inside the jail
+      - User to execute as inside the jail.
     type: string
     vars:
       - name: ansible_user
       - name: ansible_iocage_user
-'''
+"""
 
 import subprocess
 

plugins/connection/jail.py

@@ -10,16 +10,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+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
+  - Run commands or put/fetch files to an existing jail.
 options:
   remote_addr:
     description:
-            - Path to the jail
+      - Path to the jail.
     type: string
     default: inventory_hostname
     vars:
@@ -28,12 +28,12 @@ DOCUMENTATION = '''
       - name: ansible_jail_host
   remote_user:
     description:
-            - User to execute as inside the jail
+      - 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,16 +7,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Joerg Thalheim (!UNKNOWN) <joerg@higgsboson.tk>
 name: lxc
-    short_description: Run tasks in lxc containers via lxc python library
+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
+  - Run commands or put/fetch files to an existing LXC container using lxc python library.
 options:
   remote_addr:
     description:
-            - Container identifier
+      - Container identifier.
     type: string
     default: inventory_hostname
     vars:
@@ -26,12 +26,12 @@ DOCUMENTATION = '''
   executable:
     default: /bin/sh
     description:
-            - Shell executable
+      - Shell executable.
     type: string
     vars:
       - name: ansible_executable
       - name: ansible_lxc_executable
-'''
+"""
 
 import os
 import shutil

plugins/connection/lxd.py

@@ -7,18 +7,18 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Matt Clay (@mattclay) <matt@mystile.com>
 name: lxd
-    short_description: Run tasks in LXD instances via C(lxc) CLI
+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:
       - 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.
+      - 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:
@@ -48,7 +48,7 @@ DOCUMENTATION = '''
     vars:
       - name: ansible_lxd_project
     version_added: 2.0.0
-'''
+"""
 
 import os
 from subprocess import Popen, PIPE

plugins/connection/qubes.py

@@ -12,13 +12,12 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 
-DOCUMENTATION = '''
+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)
 
 
@@ -39,7 +38,7 @@ DOCUMENTATION = '''
       - 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 = '''
+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,7 +11,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Ansible Core Team
 name: zone
 short_description: Run tasks in a zone instance
@@ -20,13 +20,13 @@ DOCUMENTATION = '''
 options:
   remote_addr:
     description:
-            - Zone identifier
+      - Zone identifier.
     type: string
     default: inventory_hostname
     vars:
       - name: ansible_host
       - name: ansible_zone_host
-'''
+"""
 
 import os
 import os.path