[PR #5760/9e3a729d backport][stable-6] Improve callback docs (#5784)

Improve callback docs (#5760)

* Improve callback docs.

* Apply suggestions from code review

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

* Update plugins/callback/logentries.py

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

* More improvements.

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

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>
(cherry picked from commit 9e3a729da9)

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

plugins/callback/cgroup_memory_recap.py

@@ -16,15 +16,15 @@ 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 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 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 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 C(/sys/fs/cgroup/memory/ansible_profile/memory.max_usage_in_bytes)
+        description: Path to cgroups C(memory.max_usage_in_bytes) file. Example C(/sys/fs/cgroup/memory/ansible_profile/memory.max_usage_in_bytes).
         env:
           - name: CGROUP_MAX_MEM_FILE
         ini:
@@ -32,7 +32,7 @@ DOCUMENTATION = '''
             key: max_mem_file
       cur_mem_file:
         required: true
-        description: Path to C(memory.usage_in_bytes) file. Example C(/sys/fs/cgroup/memory/ansible_profile/memory.usage_in_bytes)
+        description: Path to C(memory.usage_in_bytes) file. Example C(/sys/fs/cgroup/memory/ansible_profile/memory.usage_in_bytes).
         env:
           - name: CGROUP_CUR_MEM_FILE
         ini:

plugins/callback/context_demo.py

@@ -13,8 +13,8 @@ DOCUMENTATION = '''
     type: aggregate
     short_description: demo callback that adds play/task context
     description:
-      - Displays some play and task context along with normal output
+      - Displays some play and task context along with normal output.
-      - This is mostly for demo purposes
+      - This is mostly for demo purposes.
     requirements:
       - whitelist in configuration
 '''

plugins/callback/counter_enabled.py

@@ -21,7 +21,7 @@ DOCUMENTATION = '''
     extends_documentation_fragment:
       - default_callback
     requirements:
-      - set as stdout callback in ansible.cfg  (stdout_callback = counter_enabled)
+      - set as stdout callback in C(ansible.cfg) (C(stdout_callback = counter_enabled))
 '''
 
 from ansible import constants as C

plugins/callback/dense.py

@@ -14,7 +14,7 @@ short_description: minimal stdout output
 extends_documentation_fragment:
 - 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)
 requirements:

plugins/callback/jabber.py

@@ -13,10 +13,10 @@ DOCUMENTATION = '''
     type: notification
     short_description: post task events to a jabber server
     description:
-      - The chatty part of ChatOps with a Hipchat server as a target
+      - 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:
-      - xmpp (python lib https://github.com/ArchipelProject/xmpppy)
+      - xmpp (Python library U(https://github.com/ArchipelProject/xmpppy))
     options:
       server:
         description: connection info to jabber server

plugins/callback/log_plays.py

@@ -13,10 +13,10 @@ DOCUMENTATION = '''
     type: notification
     short_description: write playbook output to log file
     description:
-      - This callback writes playbook output to a file per host in the C(/var/log/ansible/hosts) directory
+      - This callback writes playbook output to a file per host in the C(/var/log/ansible/hosts) directory.
     requirements:
      - Whitelist in configuration
-     - A writeable /var/log/ansible/hosts directory by the user executing Ansible on the controller
+     - A writeable C(/var/log/ansible/hosts) directory by the user executing Ansible on the controller
     options:
       log_folder:
         default: /var/log/ansible/hosts

plugins/callback/logdna.py

@@ -12,14 +12,14 @@ DOCUMENTATION = '''
     type: notification
     short_description: Sends playbook logs to LogDNA
     description:
-      - This callback will report logs from playbook actions, tasks, and events to LogDNA (https://app.logdna.com)
+      - This callback will report logs from playbook actions, tasks, and events to LogDNA (U(https://app.logdna.com)).
     requirements:
-      - LogDNA Python Library (https://github.com/logdna/python)
+      - LogDNA Python Library (U(https://github.com/logdna/python))
       - whitelisting in configuration
     options:
       conf_key:
         required: true
-        description: LogDNA Ingestion Key
+        description: LogDNA Ingestion Key.
         type: string
         env:
           - name: LOGDNA_INGESTION_KEY
@@ -28,7 +28,7 @@ DOCUMENTATION = '''
             key: conf_key
       plugin_ignore_errors:
         required: false
-        description: Whether to ignore errors on failing or not
+        description: Whether to ignore errors on failing or not.
         type: boolean
         env:
           - name: ANSIBLE_IGNORE_ERRORS
@@ -38,7 +38,7 @@ DOCUMENTATION = '''
         default: false
       conf_hostname:
         required: false
-        description: Alternative Host Name; the current host name by default
+        description: Alternative Host Name; the current host name by default.
         type: string
         env:
           - name: LOGDNA_HOSTNAME
@@ -47,7 +47,7 @@ DOCUMENTATION = '''
             key: conf_hostname
       conf_tags:
         required: false
-        description: Tags
+        description: Tags.
         type: string
         env:
           - name: LOGDNA_TAGS

plugins/callback/logentries.py

@@ -13,15 +13,15 @@ DOCUMENTATION = '''
     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.
-      - 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 logentries.ini
+      - 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)
+      - certifi (Python library)
-      - flatdict (python library), if you want to use the 'flatten' option
+      - flatdict (Python library), if you want to use the 'flatten' option
     options:
       api:
-        description: URI to the Logentries API
+        description: URI to the Logentries API.
         env:
           - name: LOGENTRIES_API
         default: data.logentries.com
@@ -29,7 +29,7 @@ DOCUMENTATION = '''
           - section: callback_logentries
             key: api
       port:
-        description: HTTP port to use when connecting to the API
+        description: HTTP port to use when connecting to the API.
         env:
             - name: LOGENTRIES_PORT
         default: 80
@@ -37,7 +37,7 @@ DOCUMENTATION = '''
           - section: callback_logentries
             key: port
       tls_port:
-        description: Port to use when connecting to the API when TLS is enabled
+        description: Port to use when connecting to the API when TLS is enabled.
         env:
             - name: LOGENTRIES_TLS_PORT
         default: 443
@@ -45,7 +45,7 @@ DOCUMENTATION = '''
           - section: callback_logentries
             key: tls_port
       token:
-        description: The logentries "TCP token"
+        description: The logentries C(TCP token).
         env:
           - name: LOGENTRIES_ANSIBLE_TOKEN
         required: true
@@ -54,7 +54,7 @@ DOCUMENTATION = '''
             key: token
       use_tls:
         description:
-          - Toggle to decide whether to use TLS to encrypt the communications with the API server
+          - Toggle to decide whether to use TLS to encrypt the communications with the API server.
         env:
           - name: LOGENTRIES_USE_TLS
         default: false
@@ -63,7 +63,7 @@ DOCUMENTATION = '''
           - section: callback_logentries
             key: use_tls
       flatten:
-        description: flatten complex data structures into a single dictionary with complex keys
+        description: Flatten complex data structures into a single dictionary with complex keys.
         type: boolean
         default: false
         env:

plugins/callback/logstash.py

@@ -13,13 +13,13 @@ DOCUMENTATION = r'''
     type: notification
     short_description: Sends events to Logstash
     description:
-      - This callback will report facts and task events to Logstash https://www.elastic.co/products/logstash
+      - This callback will report facts and task events to Logstash U(https://www.elastic.co/products/logstash).
     requirements:
       - whitelisting in configuration
-      - logstash (python library)
+      - logstash (Python library)
     options:
       server:
-        description: Address of the Logstash server
+        description: Address of the Logstash server.
         env:
           - name: LOGSTASH_SERVER
         ini:
@@ -28,7 +28,7 @@ DOCUMENTATION = r'''
             version_added: 1.0.0
         default: localhost
       port:
-        description: Port on which logstash is listening
+        description: Port on which logstash is listening.
         env:
             - name: LOGSTASH_PORT
         ini:
@@ -37,7 +37,7 @@ DOCUMENTATION = r'''
             version_added: 1.0.0
         default: 5000
       type:
-        description: Message type
+        description: Message type.
         env:
           - name: LOGSTASH_TYPE
         ini:
@@ -54,7 +54,7 @@ DOCUMENTATION = r'''
         env:
           - name: LOGSTASH_PRE_COMMAND
       format_version:
-        description: Logging format
+        description: Logging format.
         type: str
         version_added: 2.0.0
         ini:

plugins/callback/null.py

@@ -15,7 +15,7 @@ DOCUMENTATION = '''
       - set as main display callback
     short_description: Don't display stuff to screen
     description:
-        - This callback prevents outputing events to screen
+        - This callback prevents outputing events to screen.
 '''
 
 from ansible.plugins.callback import CallbackBase

plugins/callback/say.py

@@ -14,12 +14,12 @@ DOCUMENTATION = '''
     type: notification
     requirements:
       - whitelisting in configuration
-      - the '/usr/bin/say' command line program (standard on macOS) or 'espeak' command line program
+      - the C(/usr/bin/say) command line program (standard on macOS) or C(espeak) command line program
     short_description: notify using software speech synthesizer
     description:
-      - This plugin will use the 'say' or 'espeak' program to "speak" about play events.
+      - This plugin will use the C(say) or C(espeak) program to "speak" about play events.
     notes:
-      - In 2.8, this callback has been renamed from C(osx_say) into M(community.general.say).
+      - In Ansible 2.8, this callback has been renamed from C(osx_say) into M(community.general.say).
 '''
 
 import platform

plugins/callback/selective.py

@@ -22,7 +22,7 @@ DOCUMENTATION = '''
     options:
       nocolor:
         default: false
-        description: This setting allows suppressing colorizing output
+        description: This setting allows suppressing colorizing output.
         env:
           - name: ANSIBLE_NOCOLOR
           - name: ANSIBLE_SELECTIVE_DONT_COLORIZE

plugins/callback/slack.py

@@ -18,11 +18,11 @@ DOCUMENTATION = '''
     short_description: Sends play events to a Slack channel
     description:
         - This is an ansible callback plugin that sends status updates to a Slack channel during playbook execution.
-        - Before 2.4 only environment variables were available for configuring this plugin
+        - Before Ansible 2.4 only environment variables were available for configuring this plugin.
     options:
       webhook_url:
         required: true
-        description: Slack Webhook URL
+        description: Slack Webhook URL.
         env:
           - name: SLACK_WEBHOOK_URL
         ini:
@@ -45,7 +45,7 @@ DOCUMENTATION = '''
           - section: callback_slack
             key: username
       validate_certs:
-        description: validate the SSL certificate of the Slack server. (For HTTPS URLs)
+        description: Validate the SSL certificate of the Slack server for HTTPS URLs.
         env:
           - name: SLACK_VALIDATE_CERTS
         ini:

plugins/callback/splunk.py

@@ -13,22 +13,22 @@ DOCUMENTATION = '''
     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 "https://splunkbase.splunk.com/app/4023/"
+      - 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 ansible.cfg'
+      - 'Define the URL and token in C(ansible.cfg)'
     options:
       url:
-        description: URL to the Splunk HTTP collector source
+        description: URL to the Splunk HTTP collector source.
         env:
           - name: SPLUNK_URL
         ini:
           - section: callback_splunk
             key: url
       authtoken:
-        description: Token to authenticate the connection to the Splunk HTTP collector
+        description: Token to authenticate the connection to the Splunk HTTP collector.
         env:
           - name: SPLUNK_AUTHTOKEN
         ini:
@@ -48,7 +48,7 @@ DOCUMENTATION = '''
         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
+                     sent to the Splunk HTTP collector.
         env:
           - name: SPLUNK_INCLUDE_MILLISECONDS
         ini:

plugins/callback/sumologic.py

@@ -12,14 +12,14 @@ type: notification
 short_description: Sends task result events to Sumologic
 author: "Ryan Currah (@ryancurrah)"
 description:
-  - This callback plugin will send task results as JSON formatted events to a Sumologic HTTP collector source
+  - 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 C(yyyy-MM-dd HH:mm:ss ZZZZ) and a custom timestamp locator
     of C("timestamp": "(.*)")'
 options:
   url:
-    description: URL to the Sumologic HTTP collector source
+    description: URL to the Sumologic HTTP collector source.
     env:
       - name: SUMOLOGIC_URL
     ini:
@@ -28,7 +28,7 @@ options:
 '''
 
 EXAMPLES = '''
-examples: >
+examples: |
   To enable, add this to your ansible.cfg file in the defaults block
     [defaults]
     callback_whitelist = community.general.sumologic

plugins/callback/syslog_json.py

@@ -15,11 +15,11 @@ DOCUMENTATION = '''
       - whitelist in configuration
     short_description: sends JSON events to syslog
     description:
-      - This plugin logs ansible-playbook and ansible runs to a syslog server in JSON format
+      - This plugin logs ansible-playbook and ansible runs to a syslog server in JSON format.
-      - Before Ansible 2.9 only environment variables were available for configuration
+      - Before Ansible 2.9 only environment variables were available for configuration.
     options:
       server:
-        description: syslog server that will receive the event
+        description: Syslog server that will receive the event.
         env:
         - name: SYSLOG_SERVER
         default: localhost
@@ -27,7 +27,7 @@ DOCUMENTATION = '''
           - section: callback_syslog_json
             key: syslog_server
       port:
-        description: port on which the syslog server is listening
+        description: Port on which the syslog server is listening.
         env:
           - name: SYSLOG_PORT
         default: 514
@@ -35,7 +35,7 @@ DOCUMENTATION = '''
           - section: callback_syslog_json
             key: syslog_port
       facility:
-        description: syslog facility to log as
+        description: Syslog facility to log as.
         env:
           - name: SYSLOG_FACILITY
         default: user

plugins/callback/yaml.py

@@ -11,7 +11,7 @@ DOCUMENTATION = '''
     author: Unknown (!UNKNOWN)
     name: yaml
     type: stdout
-    short_description: yaml-ized Ansible screen output
+    short_description: YAML-ized Ansible screen output
     description:
         - Ansible output that can be quite a bit easier to read than the
           default JSON formatting.