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,21 +7,22 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    author: Unknown (!UNKNOWN)
+author: Unknown (!UNKNOWN)
-    name: cgroup_memory_recap
+name: cgroup_memory_recap
-    type: aggregate
+type: aggregate
-    requirements:
+requirements:
   - whitelist in configuration
   - cgroups
-    short_description: Profiles maximum memory usage of tasks and full execution using cgroups
+short_description: Profiles maximum memory usage of tasks and full execution using cgroups
-    description:
+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
-    notes:
+    recap at the end using cgroups.
-        - Requires ansible to be run from within a cgroup, such as with C(cgexec -g memory:ansible_profile ansible-playbook ...).
+notes:
-        - This cgroup should only be used by ansible to get accurate results.
+  - Requires ansible to be run from within a C(cgroup), such as with C(cgexec -g memory:ansible_profile ansible-playbook ...).
-        - 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).
+  - This C(cgroup) should only be used by Ansible to get accurate results.
-    options:
+  - 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
     description: Path to cgroups C(memory.max_usage_in_bytes) file. Example V(/sys/fs/cgroup/memory/ansible_profile/memory.max_usage_in_bytes).
@@ -40,7 +41,7 @@ DOCUMENTATION = '''
     ini:
       - section: callback_cgroupmemrecap
         key: cur_mem_file
-'''
+"""
 
 import time
 import threading

plugins/callback/context_demo.py

@@ -7,17 +7,17 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    author: Unknown (!UNKNOWN)
+author: Unknown (!UNKNOWN)
-    name: context_demo
+name: context_demo
-    type: aggregate
+type: aggregate
-    short_description: demo callback that adds play/task context
+short_description: demo callback that adds play/task context
-    description:
+description:
   - Displays some play and task context along with normal output.
   - This is mostly for demo purposes.
-    requirements:
+requirements:
   - whitelist in configuration
-'''
+"""
 
 from ansible.plugins.callback import CallbackBase
 

plugins/callback/counter_enabled.py

@@ -9,20 +9,20 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    author: Unknown (!UNKNOWN)
+author: Unknown (!UNKNOWN)
-    name: counter_enabled
+name: counter_enabled
-    type: stdout
+type: stdout
-    short_description: adds counters to the output items (tasks and hosts/task)
+short_description: adds counters to the output items (tasks and hosts/task)
-    description:
+description:
   - Use this callback when you need a kind of progress bar on a large environments.
   - You will know how many tasks has the playbook to run, and which one is actually running.
   - You will know how many hosts may run a task, and which of them is actually running.
-    extends_documentation_fragment:
+extends_documentation_fragment:
   - default_callback
-    requirements:
+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
+name: default_without_diff
-  type: stdout
+type: stdout
-  short_description: The default ansible callback without diff output
+short_description: The default ansible callback without diff output
-  version_added: 8.4.0
+version_added: 8.4.0
-  description:
+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)
-  author: Felix Fontein (@felixfontein)
+extends_documentation_fragment:
-  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,19 +7,19 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
 name: dense
 type: stdout
 short_description: minimal stdout output
 extends_documentation_fragment:
-- default_callback
+  - default_callback
 description:
-- When in verbose mode it will act the same as the default callback.
+  - When in verbose mode it will act the same as the default callback.
 author:
-- Dag Wieers (@dagwieers)
+  - Dag Wieers (@dagwieers)
 requirements:
-- set as stdout in configuration
+  - set as stdout in configuration
-'''
+"""
 
 HAS_OD = False
 try:

plugins/callback/diy.py

@@ -7,48 +7,43 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
-  name: diy
+name: diy
-  type: stdout
+type: stdout
-  short_description: Customize the output
+short_description: Customize the output
-  version_added: 0.2.0
+version_added: 0.2.0
-  description:
+description:
   - Callback plugin that allows you to supply your own custom callback templates to be output.
-  author: Trevor Highfill (@theque5t)
+author: Trevor Highfill (@theque5t)
-  extends_documentation_fragment:
+extends_documentation_fragment:
   - default_callback
-  notes:
+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),
+seealso:
-                    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.
     link: https://docs.ansible.com/ansible/latest/plugins/callback/default.html
-  requirements:
+requirements:
   - set as stdout_callback in configuration
-  options:
+options:
   on_any_msg:
     description: Output to be used for callback on_any.
     ini:
@@ -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,17 +5,17 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    author: Victor Martinez (@v1v)  <VictorMartinezRubio@gmail.com>
+author: Victor Martinez (@v1v)  <VictorMartinezRubio@gmail.com>
-    name: elastic
+name: elastic
-    type: notification
+type: notification
-    short_description: Create distributed traces for each Ansible task in Elastic APM
+short_description: Create distributed traces for each Ansible task in Elastic APM
-    version_added: 3.8.0
+version_added: 3.8.0
-    description:
+description:
   - This callback creates distributed traces for each Ansible task in Elastic APM.
   - You can configure the plugin with environment variables.
   - See U(https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html).
-    options:
+options:
   hide_task_arguments:
     default: false
     type: bool
@@ -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:
@@ -61,13 +61,13 @@ DOCUMENTATION = '''
       - The L(W3C Trace Context header traceparent,https://www.w3.org/TR/trace-context-1/#traceparent-header).
     env:
       - name: TRACEPARENT
-    requirements:
+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,42 +7,42 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    author: Unknown (!UNKNOWN)
+author: Unknown (!UNKNOWN)
-    name: jabber
+name: jabber
-    type: notification
+type: notification
-    short_description: post task events to a jabber server
+short_description: post task events to a Jabber server
-    description:
+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.
-    requirements:
+requirements:
   - xmpp (Python library U(https://github.com/ArchipelProject/xmpppy))
-    options:
+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,17 +7,17 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    author: Unknown (!UNKNOWN)
+author: Unknown (!UNKNOWN)
-    name: log_plays
+name: log_plays
-    type: notification
+type: notification
-    short_description: write playbook output to log file
+short_description: write playbook output to log file
-    description:
+description:
   - This callback writes playbook output to a file per host in the C(/var/log/ansible/hosts) directory.
-    requirements:
+requirements:
   - Whitelist in configuration
   - A writeable C(/var/log/ansible/hosts) directory by the user executing Ansible on the controller
-    options:
+options:
   log_folder:
     default: /var/log/ansible/hosts
     description: The folder where log files will be created.
@@ -27,7 +27,7 @@ DOCUMENTATION = '''
     ini:
       - section: callback_log_plays
         key: log_folder
-'''
+"""
 
 import os
 import time

plugins/callback/loganalytics.py

@@ -6,19 +6,19 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    name: loganalytics
+name: loganalytics
-    type: notification
+type: notification
-    short_description: Posts task results to Azure Log Analytics
+short_description: Posts task results to Azure Log Analytics
-    author: "Cyrus Li (@zhcli) <cyrus1006@gmail.com>"
+author: "Cyrus Li (@zhcli) <cyrus1006@gmail.com>"
-    description:
+description:
   - This callback plugin will post task results in JSON formatted to an Azure Log Analytics workspace.
   - Credits to authors of splunk callback plugin.
-    version_added: "2.4.0"
+version_added: "2.4.0"
-    requirements:
+requirements:
   - Whitelisting this callback plugin.
   - An Azure log analytics work space has been established.
-    options:
+options:
   workspace_id:
     description: Workspace ID of the Azure log analytics workspace.
     type: str
@@ -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,17 +6,17 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    author: Unknown (!UNKNOWN)
+author: Unknown (!UNKNOWN)
-    name: logdna
+name: logdna
-    type: notification
+type: notification
-    short_description: Sends playbook logs to LogDNA
+short_description: Sends playbook logs to LogDNA
-    description:
+description:
   - This callback will report logs from playbook actions, tasks, and events to LogDNA (U(https://app.logdna.com)).
-    requirements:
+requirements:
   - LogDNA Python Library (U(https://github.com/logdna/python))
   - whitelisting in configuration
-    options:
+options:
   conf_key:
     required: true
     description: LogDNA Ingestion Key.
@@ -55,7 +55,7 @@ DOCUMENTATION = '''
       - section: callback_logdna
         key: conf_tags
     default: ansible
-'''
+"""
 
 import logging
 import json

plugins/callback/logentries.py

@@ -6,20 +6,18 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    author: Unknown (!UNKNOWN)
+author: Unknown (!UNKNOWN)
-    name: logentries
+name: logentries
-    type: notification
+type: notification
-    short_description: Sends events to Logentries
+short_description: Sends events to Logentries
-    description:
+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).
+requirements:
-      - In 2.4 and above you can just put it in the main Ansible configuration file.
-    requirements:
   - whitelisting in configuration
   - certifi (Python library)
   - flatdict (Python library), if you want to use the O(flatten) option
-    options:
+options:
   api:
     description: URI to the Logentries API.
     type: str
@@ -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,17 +7,17 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
-    author: Yevhen Khmelenko (@ujenmr)
+author: Yevhen Khmelenko (@ujenmr)
-    name: logstash
+name: logstash
-    type: notification
+type: notification
-    short_description: Sends events to Logstash
+short_description: Sends events to Logstash
-    description:
+description:
   - This callback will report facts and task events to Logstash U(https://www.elastic.co/products/logstash).
-    requirements:
+requirements:
   - whitelisting in configuration
   - logstash (Python library)
-    options:
+options:
   server:
     description: Address of the Logstash server.
     type: str
@@ -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,16 +7,16 @@
 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)
+  - Dag Wieers (@dagwieers)
 requirements:
-- whitelisting in configuration
+  - whitelisting in configuration
 options:
   mta:
     description:
@@ -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,27 +7,27 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    name: nrdp
+name: nrdp
-    type: notification
+type: notification
-    author: "Remi VERCHERE (@rverchere)"
+author: "Remi VERCHERE (@rverchere)"
-    short_description: Post task results to a Nagios server through nrdp
+short_description: Post task results to a Nagios server through nrdp
-    description:
+description:
   - This callback send playbook result to Nagios.
   - Nagios shall use NRDP to receive passive events.
   - The passive check is sent to a dedicated host/service for Ansible.
-    options:
+options:
   url:
     description: URL of the nrdp server.
     required: true
     env:
-                - name : NRDP_URL
+      - name: NRDP_URL
     ini:
       - section: callback_nrdp
         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:
@@ -37,7 +37,7 @@ DOCUMENTATION = '''
         key: validate_certs
     type: boolean
     default: false
-            aliases: [ validate_nrdp_certs ]
+    aliases: [validate_nrdp_certs]
   token:
     description: Token to be allowed to push nrdp events.
     required: true
@@ -51,7 +51,7 @@ DOCUMENTATION = '''
     description: Hostname where the passive check is linked to.
     required: true
     env:
-                - name : NRDP_HOSTNAME
+      - name: NRDP_HOSTNAME
     ini:
       - section: callback_nrdp
         key: hostname
@@ -60,12 +60,12 @@ DOCUMENTATION = '''
     description: Service where the passive check is linked to.
     required: true
     env:
-                - name : NRDP_SERVICENAME
+      - name: NRDP_SERVICENAME
     ini:
       - 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)
+author: Unknown (!UNKNOWN)
-    name: 'null'
+name: 'null'
-    type: stdout
+type: stdout
-    requirements:
+requirements:
   - set as main display callback
-    short_description: Don't display stuff to screen
+short_description: do not display stuff to screen
-    description:
+description:
   - This callback prevents outputting events to screen.
-'''
+"""
 
 from ansible.plugins.callback import CallbackBase
 

plugins/callback/opentelemetry.py

@@ -6,18 +6,19 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    author: Victor Martinez (@v1v)  <VictorMartinezRubio@gmail.com>
+author: Victor Martinez (@v1v)  <VictorMartinezRubio@gmail.com>
-    name: opentelemetry
+name: opentelemetry
-    type: notification
+type: notification
-    short_description: Create distributed traces with OpenTelemetry
+short_description: Create distributed traces with OpenTelemetry
-    version_added: 3.7.0
+version_added: 3.7.0
-    description:
+description:
   - 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
-    options:
+    U(https://opentelemetry-python.readthedocs.io/en/latest/sdk/environment_variables.html#opentelemetry-sdk-environment-variables).
+options:
   hide_task_arguments:
     default: false
     type: bool
@@ -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:
@@ -110,15 +111,15 @@ DOCUMENTATION = '''
       - section: callback_opentelemetry
         key: otel_exporter_otlp_traces_protocol
     version_added: 9.0.0
-    requirements:
+requirements:
   - 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,17 +8,17 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    author: Unknown (!UNKNOWN)
+author: Unknown (!UNKNOWN)
-    name: say
+name: say
-    type: notification
+type: notification
-    requirements:
+requirements:
   - whitelisting in configuration
   - the C(/usr/bin/say) command line program (standard on macOS) or C(espeak) command line program
-    short_description: notify using software speech synthesizer
+short_description: notify using software speech synthesizer
-    description:
+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,19 +7,19 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    author: Unknown (!UNKNOWN)
+author: Unknown (!UNKNOWN)
-    name: selective
+name: selective
-    type: stdout
+type: stdout
-    requirements:
+requirements:
   - set as main display callback
-    short_description: only print certain tasks
+short_description: only print certain tasks
-    description:
+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:
+options:
   nocolor:
     default: false
     description: This setting allows suppressing colorizing output.
@@ -30,11 +30,11 @@ DOCUMENTATION = '''
       - section: defaults
         key: nocolor
     type: boolean
-'''
+"""
 
-EXAMPLES = """
+EXAMPLES = r"""
-  - ansible.builtin.debug: msg="This will not be printed"
+- ansible.builtin.debug: msg="This will not be printed"
-  - ansible.builtin.debug: msg="But this will"
+- ansible.builtin.debug: msg="But this will"
   tags: [print_action]
 """
 

plugins/callback/slack.py

@@ -8,17 +8,17 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    author: Unknown (!UNKNOWN)
+author: Unknown (!UNKNOWN)
-    name: slack
+name: slack
-    type: notification
+type: notification
-    requirements:
+requirements:
   - whitelist in configuration
   - prettytable (python library)
-    short_description: Sends play events to a Slack channel
+short_description: Sends play events to a Slack channel
-    description:
+description:
   - This is an ansible callback plugin that sends status updates to a Slack channel during playbook execution.
-    options:
+options:
   webhook_url:
     required: true
     description: Slack Webhook URL.
@@ -55,7 +55,7 @@ DOCUMENTATION = '''
         key: validate_certs
     default: true
     type: bool
-'''
+"""
 
 import json
 import os

plugins/callback/splunk.py

@@ -6,20 +6,20 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    name: splunk
+name: splunk
-    type: notification
+type: notification
-    short_description: Sends task result events to Splunk HTTP Event Collector
+short_description: Sends task result events to Splunk HTTP Event Collector
-    author: "Stuart Hirst (!UNKNOWN) <support@convergingdata.com>"
+author: "Stuart Hirst (!UNKNOWN) <support@convergingdata.com>"
-    description:
+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:
+requirements:
   - Whitelisting this callback plugin
   - 'Create a HTTP Event Collector in Splunk'
   - 'Define the URL and token in C(ansible.cfg)'
-    options:
+options:
   url:
     description: URL to the Splunk HTTP collector source.
     type: str
@@ -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,16 +7,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    author: Unknown (!UNKNOWN)
+author: Unknown (!UNKNOWN)
-    name: syslog_json
+name: syslog_json
-    type: notification
+type: notification
-    requirements:
+requirements:
   - whitelist in configuration
-    short_description: sends JSON events to syslog
+short_description: sends JSON events to syslog
-    description:
+description:
   - This plugin logs ansible-playbook and ansible runs to a syslog server in JSON format.
-    options:
+options:
   server:
     description: Syslog server that will receive the event.
     type: str
@@ -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

@@ -10,18 +10,18 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
 DOCUMENTATION = r"""
-  name: timestamp
+name: timestamp
-  type: stdout
+type: stdout
-  short_description: Adds simple timestamp for each header
+short_description: Adds simple timestamp for each header
-  version_added: 9.0.0
+version_added: 9.0.0
-  description:
+description:
   - This callback adds simple timestamp for each header.
-  author: kurokobo (@kurokobo)
+author: kurokobo (@kurokobo)
-  options:
+options:
   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
@@ -41,13 +40,13 @@ DOCUMENTATION = r"""
       - name: ANSIBLE_CALLBACK_TIMESTAMP_FORMAT_STRING
     default: "%H:%M:%S"
     type: string
-  seealso:
+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:
+extends_documentation_fragment:
   - ansible.builtin.default_callback
   - ansible.builtin.result_format_callback
 """

plugins/callback/unixy.py

@@ -8,18 +8,18 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    name: unixy
+name: unixy
-    type: stdout
+type: stdout
-    author: Al Bowles (@akatch)
+author: Al Bowles (@akatch)
-    short_description: condensed Ansible output
+short_description: condensed Ansible output
-    description:
+description:
   - Consolidated Ansible output in the style of LINUX/UNIX startup logs.
-    extends_documentation_fragment:
+extends_documentation_fragment:
   - default_callback
-    requirements:
+requirements:
   - set as stdout in configuration
-'''
+"""
 
 from os.path import basename
 from ansible import constants as C

plugins/callback/yaml.py

@@ -7,29 +7,27 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    author: Unknown (!UNKNOWN)
+author: Unknown (!UNKNOWN)
-    name: yaml
+name: yaml
-    type: stdout
+type: stdout
-    short_description: YAML-ized Ansible screen output
+short_description: YAML-ized Ansible screen output
-    description:
+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:
-    extends_documentation_fragment:
   - default_callback
-    requirements:
+requirements:
   - set as stdout in configuration
-    seealso:
+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:
+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