[PR #9455/d887930e backport][stable-9] normalize docs in callback plugins (#9466)

normalize docs in callback plugins (#9455)

* normalize docs in callback plugins

Normalize doc blocks for plugins

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit d887930e49)

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

plugins/callback/splunk.py

@@ -6,73 +6,73 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
-    name: splunk
-    type: notification
-    short_description: Sends task result events to Splunk HTTP Event Collector
-    author: "Stuart Hirst (!UNKNOWN) <support@convergingdata.com>"
+DOCUMENTATION = r"""
+name: splunk
+type: notification
+short_description: Sends task result events to Splunk HTTP Event Collector
+author: "Stuart Hirst (!UNKNOWN) <support@convergingdata.com>"
+description:
+  - This callback plugin will send task results as JSON formatted events to a Splunk HTTP collector.
+  - The companion Splunk Monitoring & Diagnostics App is available here U(https://splunkbase.splunk.com/app/4023/).
+  - Credit to "Ryan Currah (@ryancurrah)" for original source upon which this is based.
+requirements:
+  - Whitelisting this callback plugin
+  - 'Create a HTTP Event Collector in Splunk'
+  - 'Define the URL and token in C(ansible.cfg)'
+options:
+  url:
+    description: URL to the Splunk HTTP collector source.
+    type: str
+    env:
+      - name: SPLUNK_URL
+    ini:
+      - section: callback_splunk
+        key: url
+  authtoken:
+    description: Token to authenticate the connection to the Splunk HTTP collector.
+    type: str
+    env:
+      - name: SPLUNK_AUTHTOKEN
+    ini:
+      - section: callback_splunk
+        key: authtoken
+  validate_certs:
+    description: Whether to validate certificates for connections to HEC. It is not recommended to set to V(false) except
+      when you are sure that nobody can intercept the connection between this plugin and HEC, as setting it to V(false) allows
+      man-in-the-middle attacks!
+    env:
+      - name: SPLUNK_VALIDATE_CERTS
+    ini:
+      - section: callback_splunk
+        key: validate_certs
+    type: bool
+    default: true
+    version_added: '1.0.0'
+  include_milliseconds:
+    description: Whether to include milliseconds as part of the generated timestamp field in the event sent to the Splunk
+      HTTP collector.
+    env:
+      - name: SPLUNK_INCLUDE_MILLISECONDS
+    ini:
+      - section: callback_splunk
+        key: include_milliseconds
+    type: bool
+    default: false
+    version_added: 2.0.0
+  batch:
     description:
-      - This callback plugin will send task results as JSON formatted events to a Splunk HTTP collector.
-      - The companion Splunk Monitoring & Diagnostics App is available here U(https://splunkbase.splunk.com/app/4023/).
-      - Credit to "Ryan Currah (@ryancurrah)" for original source upon which this is based.
-    requirements:
-      - Whitelisting this callback plugin
-      - 'Create a HTTP Event Collector in Splunk'
-      - 'Define the URL and token in C(ansible.cfg)'
-    options:
-      url:
-        description: URL to the Splunk HTTP collector source.
-        type: str
-        env:
-          - name: SPLUNK_URL
-        ini:
-          - section: callback_splunk
-            key: url
-      authtoken:
-        description: Token to authenticate the connection to the Splunk HTTP collector.
-        type: str
-        env:
-          - name: SPLUNK_AUTHTOKEN
-        ini:
-          - section: callback_splunk
-            key: authtoken
-      validate_certs:
-        description: Whether to validate certificates for connections to HEC. It is not recommended to set to
-                     V(false) except when you are sure that nobody can intercept the connection
-                     between this plugin and HEC, as setting it to V(false) allows man-in-the-middle attacks!
-        env:
-          - name: SPLUNK_VALIDATE_CERTS
-        ini:
-          - section: callback_splunk
-            key: validate_certs
-        type: bool
-        default: true
-        version_added: '1.0.0'
-      include_milliseconds:
-        description: Whether to include milliseconds as part of the generated timestamp field in the event
-                     sent to the Splunk HTTP collector.
-        env:
-          - name: SPLUNK_INCLUDE_MILLISECONDS
-        ini:
-          - section: callback_splunk
-            key: include_milliseconds
-        type: bool
-        default: false
-        version_added: 2.0.0
-      batch:
-        description:
-          - Correlation ID which can be set across multiple playbook executions.
-        env:
-          - name: SPLUNK_BATCH
-        ini:
-          - section: callback_splunk
-            key: batch
-        type: str
-        version_added: 3.3.0
-'''
+      - Correlation ID which can be set across multiple playbook executions.
+    env:
+      - name: SPLUNK_BATCH
+    ini:
+      - section: callback_splunk
+        key: batch
+    type: str
+    version_added: 3.3.0
+"""
 
-EXAMPLES = '''
-examples: >
+EXAMPLES = r"""
+examples: >-
   To enable, add this to your ansible.cfg file in the defaults block
     [defaults]
     callback_whitelist = community.general.splunk
@@ -83,7 +83,7 @@ examples: >
     [callback_splunk]
     url = http://mysplunkinstance.datapaas.io:8088/services/collector/event
     authtoken = f23blad6-5965-4537-bf69-5b5a545blabla88
-'''
+"""
 
 import json
 import uuid