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>

plugins/callback/cgroup_memory_recap.py

@@ -7,7 +7,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: cgroup_memory_recap
 type: aggregate
@@ -16,11 +16,12 @@ DOCUMENTATION = '''
   - cgroups
 short_description: Profiles maximum memory usage of tasks and full execution using cgroups
 description:
-        - This is an ansible callback plugin that profiles maximum memory usage of ansible and individual tasks, and displays a recap at the end using cgroups.
+  - This is an Ansible callback plugin that profiles maximum memory usage of Ansible and individual tasks, and displays a
+    recap at the end using cgroups.
 notes:
-        - Requires ansible to be run from within a cgroup, such as with C(cgexec -g memory:ansible_profile ansible-playbook ...).
+  - Requires ansible to be run from within a C(cgroup), such as with C(cgexec -g memory:ansible_profile ansible-playbook ...).
-        - This cgroup should only be used by ansible to get accurate results.
+  - This C(cgroup) should only be used by Ansible to get accurate results.
-        - To create the cgroup, first use a command such as C(sudo cgcreate -a ec2-user:ec2-user -t ec2-user:ec2-user -g memory:ansible_profile).
+  - To create the C(cgroup), first use a command such as C(sudo cgcreate -a ec2-user:ec2-user -t ec2-user:ec2-user -g memory:ansible_profile).
 options:
   max_mem_file:
     required: true
@@ -40,7 +41,7 @@ DOCUMENTATION = '''
     ini:
       - section: callback_cgroupmemrecap
         key: cur_mem_file
-'''
+"""
 
 import time
 import threading

plugins/callback/context_demo.py

@@ -7,7 +7,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: context_demo
 type: aggregate
@@ -17,7 +17,7 @@ DOCUMENTATION = '''
   - This is mostly for demo purposes.
 requirements:
   - whitelist in configuration
-'''
+"""
 
 from ansible.plugins.callback import CallbackBase
 

plugins/callback/counter_enabled.py

@@ -9,7 +9,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: counter_enabled
 type: stdout
@@ -22,7 +22,7 @@ DOCUMENTATION = '''
   - default_callback
 requirements:
   - set as stdout callback in C(ansible.cfg) (C(stdout_callback = counter_enabled))
-'''
+"""
 
 from ansible import constants as C
 from ansible.plugins.callback import CallbackBase

plugins/callback/default_without_diff.py

@@ -7,23 +7,22 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 name: default_without_diff
 type: stdout
 short_description: The default ansible callback without diff output
 version_added: 8.4.0
 description:
-    - This is basically the default ansible callback plugin (P(ansible.builtin.default#callback)) without
+  - This is basically the default ansible callback plugin (P(ansible.builtin.default#callback)) without showing diff output.
-      showing diff output. This can be useful when using another callback which sends more detailed information
+    This can be useful when using another callback which sends more detailed information to another service, like the L(ARA,
-      to another service, like the L(ARA, https://ara.recordsansible.org/) callback, and you want diff output
+    https://ara.recordsansible.org/) callback, and you want diff output sent to that plugin but not shown on the console output.
-      sent to that plugin but not shown on the console output.
 author: Felix Fontein (@felixfontein)
 extends_documentation_fragment:
   - ansible.builtin.default_callback
   - ansible.builtin.result_format_callback
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 # Enable callback in ansible.cfg:
 ansible_config: |
   [defaults]
@@ -32,7 +31,7 @@ ansible_config: |
 # Enable callback with environment variables:
 environment_variable: |
   ANSIBLE_STDOUT_CALLBACK=community.general.default_without_diff
-'''
+"""
 
 from ansible.plugins.callback.default import CallbackModule as Default
 

plugins/callback/dense.py

@@ -7,7 +7,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: dense
 type: stdout
 short_description: minimal stdout output
@@ -19,7 +19,7 @@ author:
   - Dag Wieers (@dagwieers)
 requirements:
   - set as stdout in configuration
-'''
+"""
 
 HAS_OD = False
 try:

plugins/callback/diy.py

@@ -7,7 +7,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 name: diy
 type: stdout
 short_description: Customize the output
@@ -19,29 +19,24 @@ DOCUMENTATION = r'''
   - default_callback
 notes:
   - Uses the P(ansible.builtin.default#callback) callback plugin output when a custom callback V(message(msg\)) is not provided.
-    - Makes the callback event data available via the C(ansible_callback_diy) dictionary, which can be used in the templating context for the options.
+  - Makes the callback event data available using the C(ansible_callback_diy) dictionary, which can be used in the templating
-      The dictionary is only available in the templating context for the options. It is not a variable that is available via the other
+    context for the options. The dictionary is only available in the templating context for the options. It is not a variable
-      various execution contexts, such as playbook, play, task etc.
+    that is available using the other various execution contexts, such as playbook, play, task, and so on so forth.
-    - Options being set by their respective variable input can only be set using the variable if the variable was set in a context that is available to the
+  - Options being set by their respective variable input can only be set using the variable if the variable was set in a context
-      respective callback.
+    that is available to the respective callback. Use the C(ansible_callback_diy) dictionary to see what is available to a
-      Use the C(ansible_callback_diy) dictionary to see what is available to a callback. Additionally, C(ansible_callback_diy.top_level_var_names) will output
+    callback. Additionally, C(ansible_callback_diy.top_level_var_names) will output the top level variable names available
-      the top level variable names available to the callback.
+    to the callback.
-    - Each option value is rendered as a template before being evaluated. This allows for the dynamic usage of an option. For example,
+  - Each option value is rendered as a template before being evaluated. This allows for the dynamic usage of an option. For
-      C("{{ 'yellow' if ansible_callback_diy.result.is_changed else 'bright green' }}")
+    example, C("{{ 'yellow' if ansible_callback_diy.result.is_changed else 'bright green' }}").
-    - "**Condition** for all C(msg) options:
+  - 'B(Condition) for all C(msg) options: if value C(is None or omit), then the option is not being used. B(Effect): use
-                    if value C(is None or omit),
+    of the C(default) callback plugin for output.'
-                    then the option is not being used.
+  - 'B(Condition) for all C(msg) options: if value C(is not None and not omit and length is not greater than 0), then the
-       **Effect**: use of the C(default) callback plugin for output"
+    option is being used without output. B(Effect): suppress output.'
-    - "**Condition** for all C(msg) options:
+  - 'B(Condition) for all C(msg) options: if value C(is not None and not omit and length is greater than 0), then the option
-                    if value C(is not None and not omit and length is not greater than 0),
+    is being used with output. B(Effect): render value as template and output.'
-                    then the option is being used without output.
+  - 'Valid color values: V(black), V(bright gray), V(blue), V(white), V(green), V(bright blue), V(cyan), V(bright green),
-       **Effect**: suppress output"
+    V(red), V(bright cyan), V(purple), V(bright red), V(yellow), V(bright purple), V(dark gray), V(bright yellow), V(magenta),
-    - "**Condition** for all C(msg) options:
+    V(bright magenta), V(normal).'
-                    if value C(is not None and not omit and length is greater than 0),
-                    then the option is being used with output.
-       **Effect**: render value as template and output"
-    - "Valid color values: V(black), V(bright gray), V(blue), V(white), V(green), V(bright blue), V(cyan), V(bright green), V(red), V(bright cyan),
-      V(purple), V(bright red), V(yellow), V(bright purple), V(dark gray), V(bright yellow), V(magenta), V(bright magenta), V(normal)"
 seealso:
   - name: default – default Ansible screen output
     description: The official documentation on the B(default) callback plugin.
@@ -600,9 +595,9 @@ DOCUMENTATION = r'''
     vars:
       - name: ansible_callback_diy_playbook_on_setup_msg_color
     type: str
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 ansible.cfg: >
   # Enable plugin
   [defaults]
@@ -623,7 +618,7 @@ ansible.cfg: >
   # Newline after every callback
   # on_any_msg='{{ " " | join("\n") }}'
 
-playbook.yml: >
+playbook.yml: >-
   ---
   - name: "Default plugin output: play example"
     hosts: localhost
@@ -782,7 +777,7 @@ playbook.yml: >
               {{ white }}{{ ansible_callback_diy[key] }}
 
             {% endfor %}
-'''
+"""
 
 import sys
 from contextlib import contextmanager

plugins/callback/elastic.py

@@ -5,7 +5,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Victor Martinez (@v1v)  <VictorMartinezRubio@gmail.com>
 name: elastic
 type: notification
@@ -39,13 +39,13 @@ DOCUMENTATION = '''
   apm_secret_token:
     type: str
     description:
-          - Use the APM server token
+      - Use the APM server token.
     env:
       - name: ELASTIC_APM_SECRET_TOKEN
   apm_api_key:
     type: str
     description:
-          - Use the APM API key
+      - Use the APM API key.
     env:
       - name: ELASTIC_APM_API_KEY
   apm_verify_server_cert:
@@ -63,11 +63,11 @@ DOCUMENTATION = '''
       - name: TRACEPARENT
 requirements:
   - elastic-apm (Python library)
-'''
+"""
 
 
-EXAMPLES = '''
+EXAMPLES = r"""
-examples: |
+examples: |-
   Enable the plugin in ansible.cfg:
     [defaults]
     callbacks_enabled = community.general.elastic
@@ -76,7 +76,7 @@ examples: |
     export ELASTIC_APM_SERVER_URL=<your APM server URL)>
     export ELASTIC_APM_SERVICE_NAME=your_service_name
     export ELASTIC_APM_API_KEY=your_APM_API_KEY
-'''
+"""
 
 import getpass
 import socket

plugins/callback/jabber.py

@@ -7,11 +7,11 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: jabber
 type: notification
-    short_description: post task events to a jabber server
+short_description: post task events to a Jabber server
 description:
   - The chatty part of ChatOps with a Hipchat server as a target.
   - This callback plugin sends status updates to a HipChat channel during playbook execution.
@@ -19,30 +19,30 @@ DOCUMENTATION = '''
   - xmpp (Python library U(https://github.com/ArchipelProject/xmpppy))
 options:
   server:
-        description: connection info to jabber server
+    description: Connection info to Jabber server.
     type: str
     required: true
     env:
       - name: JABBER_SERV
   user:
-        description: Jabber user to authenticate as
+    description: Jabber user to authenticate as.
     type: str
     required: true
     env:
       - name: JABBER_USER
   password:
-        description: Password for the user to the jabber server
+    description: Password for the user to the Jabber server.
     type: str
     required: true
     env:
       - name: JABBER_PASS
   to:
-        description: chat identifier that will receive the message
+    description: Chat identifier that will receive the message.
     type: str
     required: true
     env:
       - name: JABBER_TO
-'''
+"""
 
 import os
 

plugins/callback/log_plays.py

@@ -7,7 +7,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: log_plays
 type: notification
@@ -27,7 +27,7 @@ DOCUMENTATION = '''
     ini:
       - section: callback_log_plays
         key: log_folder
-'''
+"""
 
 import os
 import time

plugins/callback/loganalytics.py

@@ -6,7 +6,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: loganalytics
 type: notification
 short_description: Posts task results to Azure Log Analytics
@@ -37,10 +37,10 @@ DOCUMENTATION = '''
     ini:
       - section: callback_loganalytics
         key: shared_key
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
-examples: |
+examples: |-
   Whitelist the plugin in ansible.cfg:
     [defaults]
     callback_whitelist = community.general.loganalytics
@@ -51,7 +51,7 @@ examples: |
     [callback_loganalytics]
     workspace_id = 01234567-0123-0123-0123-01234567890a
     shared_key = dZD0kCbKl3ehZG6LHFMuhtE0yHiFCmetzFMc2u+roXIUQuatqU924SsAAAAPemhjbGlAemhjbGktTUJQAQIDBA==
-'''
+"""
 
 import hashlib
 import hmac

plugins/callback/logdna.py

@@ -6,7 +6,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: logdna
 type: notification
@@ -55,7 +55,7 @@ DOCUMENTATION = '''
       - section: callback_logdna
         key: conf_tags
     default: ansible
-'''
+"""
 
 import logging
 import json

plugins/callback/logentries.py

@@ -6,15 +6,13 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: logentries
 type: notification
 short_description: Sends events to Logentries
 description:
-      - This callback plugin will generate JSON objects and send them to Logentries via TCP for auditing/debugging purposes.
+  - This callback plugin will generate JSON objects and send them to Logentries using TCP for auditing/debugging purposes.
-      - Before 2.4, if you wanted to use an ini configuration, the file must be placed in the same directory as this plugin and named C(logentries.ini).
-      - In 2.4 and above you can just put it in the main Ansible configuration file.
 requirements:
   - whitelisting in configuration
   - certifi (Python library)
@@ -75,10 +73,10 @@ DOCUMENTATION = '''
     ini:
       - section: callback_logentries
         key: flatten
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
-examples: >
+examples: >-
   To enable, add this to your ansible.cfg file in the defaults block
 
     [defaults]
@@ -97,7 +95,7 @@ examples: >
     use_tls = true
     token = dd21fc88-f00a-43ff-b977-e3a4233c53af
     flatten = false
-'''
+"""
 
 import os
 import socket

plugins/callback/logstash.py

@@ -7,7 +7,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 author: Yevhen Khmelenko (@ujenmr)
 name: logstash
 type: notification
@@ -70,10 +70,9 @@ DOCUMENTATION = r'''
     choices:
       - v1
       - v2
+"""
 
-'''
+EXAMPLES = r"""
-
-EXAMPLES = r'''
 ansible.cfg: |
   # Enable Callback plugin
   [defaults]
@@ -85,7 +84,7 @@ ansible.cfg: |
       pre_command = git rev-parse HEAD
       type = ansible
 
-11-input-tcp.conf: |
+11-input-tcp.conf: |-
   # Enable Logstash TCP Input
   input {
           tcp {
@@ -95,7 +94,7 @@ ansible.cfg: |
               add_field => { "[@metadata][type]" => "ansible" }
           }
       }
-'''
+"""
 
 import os
 import json

plugins/callback/mail.py

@@ -7,12 +7,12 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: mail
 type: notification
-short_description: Sends failure events via email
+short_description: Sends failure events through email
 description:
-- This callback will report failures via email.
+  - This callback will report failures through email.
 author:
   - Dag Wieers (@dagwieers)
 requirements:
@@ -80,8 +80,7 @@ options:
       - section: callback_mail
         key: message_id_domain
     version_added: 8.2.0
-
+"""
-'''
 
 import json
 import os

plugins/callback/nrdp.py

@@ -7,7 +7,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: nrdp
 type: notification
 author: "Remi VERCHERE (@rverchere)"
@@ -27,7 +27,7 @@ DOCUMENTATION = '''
         key: url
     type: string
   validate_certs:
-            description: Validate the SSL certificate of the nrdp server. (Used for HTTPS URLs.)
+    description: Validate the SSL certificate of the nrdp server. (Used for HTTPS URLs).
     env:
       - name: NRDP_VALIDATE_CERTS
     ini:
@@ -65,7 +65,7 @@ DOCUMENTATION = '''
       - section: callback_nrdp
         key: servicename
     type: string
-'''
+"""
 
 from ansible.module_utils.six.moves.urllib.parse import urlencode
 from ansible.module_utils.common.text.converters import to_bytes

plugins/callback/null.py

@@ -7,16 +7,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: 'null'
 type: stdout
 requirements:
   - set as main display callback
-    short_description: Don't display stuff to screen
+short_description: do not display stuff to screen
 description:
   - This callback prevents outputting events to screen.
-'''
+"""
 
 from ansible.plugins.callback import CallbackBase
 

plugins/callback/opentelemetry.py

@@ -6,7 +6,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Victor Martinez (@v1v)  <VictorMartinezRubio@gmail.com>
 name: opentelemetry
 type: notification
@@ -16,7 +16,8 @@ DOCUMENTATION = '''
   - This callback creates distributed traces for each Ansible task with OpenTelemetry.
   - You can configure the OpenTelemetry exporter and SDK with environment variables.
   - See U(https://opentelemetry-python.readthedocs.io/en/latest/exporter/otlp/otlp.html).
-      - See U(https://opentelemetry-python.readthedocs.io/en/latest/sdk/environment_variables.html#opentelemetry-sdk-environment-variables).
+  - See
+    U(https://opentelemetry-python.readthedocs.io/en/latest/sdk/environment_variables.html#opentelemetry-sdk-environment-variables).
 options:
   hide_task_arguments:
     default: false
@@ -33,10 +34,10 @@ DOCUMENTATION = '''
     type: str
     description:
       - Whether to enable this callback only if the given environment variable exists and it is set to V(true).
-          - This is handy when you use Configuration as Code and want to send distributed traces
+      - This is handy when you use Configuration as Code and want to send distributed traces if running in the CI rather when
-            if running in the CI rather when running Ansible locally.
+        running Ansible locally.
-          - For such, it evaluates the given O(enable_from_environment) value as environment variable
+      - For such, it evaluates the given O(enable_from_environment) value as environment variable and if set to true this
-            and if set to true this plugin will be enabled.
+        plugin will be enabled.
     env:
       - name: ANSIBLE_OPENTELEMETRY_ENABLE_FROM_ENVIRONMENT
     ini:
@@ -87,7 +88,7 @@ DOCUMENTATION = '''
   store_spans_in_file:
     type: str
     description:
-          -  It stores the exported spans in the given file
+      - It stores the exported spans in the given file.
     env:
       - name: ANSIBLE_OPENTELEMETRY_STORE_SPANS_IN_FILE
     ini:
@@ -114,11 +115,11 @@ DOCUMENTATION = '''
   - opentelemetry-api (Python library)
   - opentelemetry-exporter-otlp (Python library)
   - opentelemetry-sdk (Python library)
-'''
+"""
 
 
-EXAMPLES = '''
+EXAMPLES = r"""
-examples: |
+examples: |-
   Enable the plugin in ansible.cfg:
     [defaults]
     callbacks_enabled = community.general.opentelemetry
@@ -130,7 +131,7 @@ examples: |
     export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer your_otel_token"
     export OTEL_SERVICE_NAME=your_service_name
     export ANSIBLE_OPENTELEMETRY_ENABLED=true
-'''
+"""
 
 import getpass
 import json

plugins/callback/say.py

@@ -8,7 +8,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: say
 type: notification
@@ -18,7 +18,7 @@ DOCUMENTATION = '''
 short_description: notify using software speech synthesizer
 description:
   - This plugin will use the C(say) or C(espeak) program to "speak" about play events.
-'''
+"""
 
 import platform
 import subprocess

plugins/callback/selective.py

@@ -7,7 +7,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: selective
 type: stdout
@@ -15,8 +15,8 @@ DOCUMENTATION = '''
   - set as main display callback
 short_description: only print certain tasks
 description:
-      - This callback only prints tasks that have been tagged with C(print_action) or that have failed.
+  - This callback only prints tasks that have been tagged with C(print_action) or that have failed. This allows operators
-        This allows operators to focus on the tasks that provide value only.
+    to focus on the tasks that provide value only.
   - Tasks that are not printed are placed with a C(.).
   - If you increase verbosity all tasks are printed.
 options:
@@ -30,9 +30,9 @@ DOCUMENTATION = '''
       - section: defaults
         key: nocolor
     type: boolean
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
 - ansible.builtin.debug: msg="This will not be printed"
 - ansible.builtin.debug: msg="But this will"
   tags: [print_action]

plugins/callback/slack.py

@@ -8,7 +8,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: slack
 type: notification
@@ -55,7 +55,7 @@ DOCUMENTATION = '''
         key: validate_certs
     default: true
     type: bool
-'''
+"""
 
 import json
 import os

plugins/callback/splunk.py

@@ -6,7 +6,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: splunk
 type: notification
 short_description: Sends task result events to Splunk HTTP Event Collector
@@ -37,9 +37,9 @@ DOCUMENTATION = '''
       - section: callback_splunk
         key: authtoken
   validate_certs:
-        description: Whether to validate certificates for connections to HEC. It is not recommended to set to
+    description: Whether to validate certificates for connections to HEC. It is not recommended to set to V(false) except
-                     V(false) except when you are sure that nobody can intercept the connection
+      when you are sure that nobody can intercept the connection between this plugin and HEC, as setting it to V(false) allows
-                     between this plugin and HEC, as setting it to V(false) allows man-in-the-middle attacks!
+      man-in-the-middle attacks!
     env:
       - name: SPLUNK_VALIDATE_CERTS
     ini:
@@ -49,8 +49,8 @@ DOCUMENTATION = '''
     default: true
     version_added: '1.0.0'
   include_milliseconds:
-        description: Whether to include milliseconds as part of the generated timestamp field in the event
+    description: Whether to include milliseconds as part of the generated timestamp field in the event sent to the Splunk
-                     sent to the Splunk HTTP collector.
+      HTTP collector.
     env:
       - name: SPLUNK_INCLUDE_MILLISECONDS
     ini:
@@ -69,10 +69,10 @@ DOCUMENTATION = '''
         key: batch
     type: str
     version_added: 3.3.0
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
-examples: >
+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

plugins/callback/sumologic.py

@@ -6,7 +6,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 name: sumologic
 type: notification
 short_description: Sends task result events to Sumologic
@@ -15,8 +15,8 @@ description:
   - This callback plugin will send task results as JSON formatted events to a Sumologic HTTP collector source.
 requirements:
   - Whitelisting this callback plugin
-  - 'Create a HTTP collector source in Sumologic and specify a custom timestamp format of V(yyyy-MM-dd HH:mm:ss ZZZZ) and a custom timestamp locator
+  - 'Create a HTTP collector source in Sumologic and specify a custom timestamp format of V(yyyy-MM-dd HH:mm:ss ZZZZ) and
-    of V("timestamp": "(.*\)")'
+    a custom timestamp locator of V("timestamp": "(.*\)")'
 options:
   url:
     description: URL to the Sumologic HTTP collector source.
@@ -26,10 +26,10 @@ options:
     ini:
       - section: callback_sumologic
         key: url
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
-examples: |
+examples: |-
   To enable, add this to your ansible.cfg file in the defaults block
     [defaults]
     callback_whitelist = community.general.sumologic
@@ -40,7 +40,7 @@ examples: |
   Set the ansible.cfg variable in the callback_sumologic block
     [callback_sumologic]
     url = https://endpoint1.collection.us2.sumologic.com/receiver/v1/http/R8moSv1d8EW9LAUFZJ6dbxCFxwLH6kfCdcBfddlfxCbLuL-BN5twcTpMk__pYy_cDmp==
-'''
+"""
 
 import json
 import uuid

plugins/callback/syslog_json.py

@@ -7,7 +7,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: syslog_json
 type: notification
@@ -54,7 +54,7 @@ DOCUMENTATION = '''
       - section: callback_syslog_json
         key: syslog_setup
     version_added: 4.5.0
-'''
+"""
 
 import logging
 import logging.handlers

plugins/callback/timestamp.py

@@ -21,7 +21,7 @@ DOCUMENTATION = r"""
   timezone:
     description:
       - Timezone to use for the timestamp in IANA time zone format.
-        - For example C(America/New_York), C(Asia/Tokyo)). Ignored on Python < 3.9.
+      - For example V(America/New_York), V(Asia/Tokyo)). Ignored on Python < 3.9.
     ini:
       - section: callback_timestamp
         key: timezone
@@ -31,8 +31,7 @@ DOCUMENTATION = r"""
   format_string:
     description:
       - Format of the timestamp shown to user in 1989 C standard format.
-        - >
+      - Refer to L(the Python documentation,https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes)
-          Refer to L(the Python documentation,https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes)
         for the available format codes.
     ini:
       - section: callback_timestamp
@@ -44,7 +43,7 @@ DOCUMENTATION = r"""
 seealso:
   - plugin: ansible.posix.profile_tasks
     plugin_type: callback
-      description: >
+    description: >-
       You can use P(ansible.posix.profile_tasks#callback) callback plugin to time individual tasks and overall execution time
       with detailed timestamps.
 extends_documentation_fragment:

plugins/callback/unixy.py

@@ -8,7 +8,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: unixy
 type: stdout
 author: Al Bowles (@akatch)
@@ -19,7 +19,7 @@ DOCUMENTATION = '''
   - default_callback
 requirements:
   - set as stdout in configuration
-'''
+"""
 
 from os.path import basename
 from ansible import constants as C

plugins/callback/yaml.py

@@ -7,14 +7,13 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 author: Unknown (!UNKNOWN)
 name: yaml
 type: stdout
 short_description: YAML-ized Ansible screen output
 description:
-        - Ansible output that can be quite a bit easier to read than the
+  - Ansible output that can be quite a bit easier to read than the default JSON formatting.
-          default JSON formatting.
 extends_documentation_fragment:
   - default_callback
 requirements:
@@ -22,14 +21,13 @@ DOCUMENTATION = '''
 seealso:
   - plugin: ansible.builtin.default
     plugin_type: callback
-        description: >
+    description: >-
-          There is a parameter O(ansible.builtin.default#callback:result_format) in P(ansible.builtin.default#callback)
+      There is a parameter O(ansible.builtin.default#callback:result_format) in P(ansible.builtin.default#callback) that allows
-          that allows you to change the output format to YAML.
+      you to change the output format to YAML.
 notes:
-      - >
+  - With ansible-core 2.13 or newer, you can instead specify V(yaml) for the parameter O(ansible.builtin.default#callback:result_format)
-        With ansible-core 2.13 or newer, you can instead specify V(yaml) for the parameter O(ansible.builtin.default#callback:result_format)
     in P(ansible.builtin.default#callback).
-'''
+"""
 
 import yaml
 import json