Port ansible doc for plugins to use DOCUMENTATION variables

* Using docstrings conflicts with the standard use of docstrings
* PYTHON_OPTIMIZE=2 will omit docstrings.  Using docstrings makes future
  changes to the plugin and module code subject to the requirement that we
  ensure it won't be run with optimization.

lib/ansible/plugins/callback/actionable.py

@@ -2,8 +2,11 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: actionable
     type: stdout
     short_description: shows only items that need attention
@@ -14,9 +17,6 @@ DOCUMENTATION:
     requirements:
       - set as stdout callback in configuration
 '''
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 from ansible.plugins.callback.default import CallbackModule as CallbackModule_default
 

lib/ansible/plugins/callback/context_demo.py

@@ -2,8 +2,10 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: context_demo
     type: aggregate
     short_description: demo callback that adds play/task context
@@ -15,9 +17,6 @@ DOCUMENTATION:
       - whitelist in configuration
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 from ansible.plugins.callback import CallbackBase
 
 

lib/ansible/plugins/callback/debug.py

@@ -1,8 +1,10 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: debug
     type: stdout
     short_description: formated stdout/stderr display
@@ -12,8 +14,6 @@ DOCUMENTATION:
     requirements:
       - set as stdout in configuration
 '''
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 from ansible.plugins.callback.default import CallbackModule as CallbackModule_default
 

lib/ansible/plugins/callback/default.py

@@ -2,8 +2,10 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: default
     type: stdout
     short_description: default Ansible screen output
@@ -35,9 +37,6 @@ DOCUMENTATION:
       - set as stdout in configuration
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 from ansible import constants as C
 from ansible.playbook.task_include import TaskInclude
 from ansible.plugins.callback import CallbackBase

lib/ansible/plugins/callback/dense.py

@@ -2,8 +2,10 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: dense
     type: stdout
     short_description: minimal stdout output
@@ -13,8 +15,6 @@ DOCUMENTATION:
     requirements:
       - set as stdout in configuation
 '''
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 from collections import MutableMapping, MutableSequence
 

lib/ansible/plugins/callback/foreman.py

@@ -4,8 +4,10 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: foreman
     type: notification
     short_description: Sends events to Foreman
@@ -38,9 +40,6 @@ DOCUMENTATION:
           - name: FOREMAN_SSL_VERIFY
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import os
 from datetime import datetime
 from collections import defaultdict

lib/ansible/plugins/callback/full_skip.py

@@ -2,8 +2,11 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: full_skip
     type: stdout
     short_description: suppreses tasks if all hosts skipped
@@ -13,9 +16,6 @@ DOCUMENTATION:
     requirements:
       - set as stdout in configuation
 '''
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 from ansible.plugins.callback.default import CallbackModule as CallbackModule_default
 

lib/ansible/plugins/callback/hipchat.py

@@ -2,8 +2,10 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: hipchat
     type: notification
     short_description: post task events to hipchat
@@ -37,9 +39,6 @@ DOCUMENTATION:
           - name: HIPCHAT_NOTIFY
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import os
 
 try:

lib/ansible/plugins/callback/jabber.py

@@ -2,8 +2,10 @@
 # Copyright (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: jabber
     type: notification
     short_description: post task events to a jabber server
@@ -36,9 +38,6 @@ DOCUMENTATION:
           - name: JABBER_TO
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import os
 
 HAS_XMPP = True

lib/ansible/plugins/callback/json.py

@@ -2,8 +2,11 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: json
     short_description: Ansbile screen output as JSON
     version_added: "2.2"
@@ -14,10 +17,6 @@ DOCUMENTATION:
       - Set as stdout in config
 '''
 
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import json
 
 from ansible.plugins.callback import CallbackBase

lib/ansible/plugins/callback/junit.py

@@ -2,8 +2,10 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: junit
     type: aggregate
     short_description: write playbook output to a JUnit file.
@@ -40,9 +42,6 @@ DOCUMENTATION:
       - junit_xml (python lib)
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import os
 import time
 import re

lib/ansible/plugins/callback/log_plays.py

@@ -2,8 +2,10 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: log_plays
     type: notification
     short_description: write playbook output to log file
@@ -16,9 +18,6 @@ DOCUMENTATION:
      - A writeable /var/log/ansible/hosts directory by the user executing Ansbile on the controller
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import os
 import time
 import json

lib/ansible/plugins/callback/logentries.py

@@ -1,9 +1,10 @@
 # (c) 2015, Logentries.com, Jimmy Tang <jimmy.tang@logentries.com>
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
 
-'''
-DOCUMENTATION:
+DOCUMENTATION = '''
     callback: logentries
     type: notification
     short_description: Sends events to Logentries
@@ -68,7 +69,10 @@ DOCUMENTATION:
         ini:
           - section: callback_logentries
             key: flatten
-EXAMPLES: >
+'''
+
+EXAMPLES = '''
+examples: >
   To enable, add this to your ansible.cfg file in the defaults block
 
     [defaults]
@@ -88,8 +92,6 @@ EXAMPLES: >
     token = dd21fc88-f00a-43ff-b977-e3a4233c53af
     flatten = False
 '''
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 import os
 import socket
@@ -112,10 +114,9 @@ except ImportError:
 from ansible.errors import AnsibleError
 from ansible.module_utils._text import to_bytes, to_text, to_native
 from ansible.plugins.callback import CallbackBase
-"""
-Todo:
-  * Better formatting of output before sending out to logentries data/api nodes.
-"""
+
+# Todo:
+#  * Better formatting of output before sending out to logentries data/api nodes.
 
 
 class PlainTextSocketAppender(object):

lib/ansible/plugins/callback/logstash.py

@@ -2,8 +2,10 @@
 # (C) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: logstash
     type: notification
     short_description: Sends events to Logstash
@@ -31,9 +33,6 @@ DOCUMENTATION:
         default: ansible
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import os
 import json
 import socket

lib/ansible/plugins/callback/mail.py

@@ -2,8 +2,10 @@
 # Copyright: (c) 2012, Dag Wieers <dag@wieers.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: mail
     type: notification
     short_description: Sends failure events via email
@@ -23,9 +25,6 @@ DOCUMENTATION:
       - "TODO: expand configuration options now that plugins can leverage Ansible's configuration"
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import json
 import os
 import smtplib

lib/ansible/plugins/callback/minimal.py

@@ -2,8 +2,11 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: minimal
     type: stdout
     short_description: minimal Ansible screen output
@@ -12,11 +15,6 @@ DOCUMENTATION:
         - This is the default output callback used by the ansible command (ad-hoc)
 '''
 
-# Make coding more python3-ish
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 from ansible.plugins.callback import CallbackBase
 from ansible import constants as C
 

lib/ansible/plugins/callback/oneline.py

@@ -2,8 +2,11 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: oneline
     type: stdout
     short_description: oneline Ansible screen output
@@ -12,10 +15,6 @@ DOCUMENTATION:
         - This is the output callback used by the -o/--one-line command line option.
 '''
 
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 from ansible.plugins.callback import CallbackBase
 from ansible import constants as C
 

lib/ansible/plugins/callback/osx_say.py

@@ -2,8 +2,11 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: osx_say
     type: notification
     requirements:
@@ -15,10 +18,6 @@ DOCUMENTATION:
       - This plugin will use the 'say' program to "speak" about play events.
 '''
 
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import subprocess
 import os
 

lib/ansible/plugins/callback/profile_roles.py

@@ -2,8 +2,11 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: profile_roles
     type: aggregate
     short_description: adds timing information to roles
@@ -14,12 +17,6 @@ DOCUMENTATION:
       - whitelisting in configuration
 '''
 
-# Make coding more python3-ish
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-
-__metaclass__ = type
-
 import collections
 import time
 

lib/ansible/plugins/callback/profile_tasks.py

@@ -5,8 +5,11 @@
 # (C) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: profile_tasks
     type: aggregate
     short_description: adds time information to tasks
@@ -38,7 +41,9 @@ DOCUMENTATION:
         ini:
           - section: callback_profile_tasks
             key: sort_order
-#EXAMPLES: > '
+'''
+
+EXAMPLES = '''
 #
 #    TASK: [ensure messaging security group exists] ********************************
 #    Thursday 11 June 2017  22:50:53 +0100 (0:00:00.721)       0:00:05.322 *********
@@ -50,11 +55,6 @@ DOCUMENTATION:
 #  '
 '''
 
-# Make coding more python3-ish
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import collections
 import time
 

lib/ansible/plugins/callback/selective.py

@@ -2,8 +2,10 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-"""
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = """
     callback: selective
     callback_type: stdout
     requirements:
@@ -26,21 +28,20 @@ DOCUMENTATION:
           - section: defaults
           - key: nocolor
         type: boolean
-EXAMPLES:
+"""
+
+EXAMPLES = """
   - debug: msg="This will not be printed"
   - debug: msg="But this will"
     tags: [print_action]
 """
 
-from __future__ import (absolute_import, division, print_function)
-
 import difflib
 
 from ansible import constants as C
 from ansible.plugins.callback import CallbackBase
 from ansible.module_utils._text import to_text
 
-__metaclass__ = type
 
 DONT_COLORIZE = False
 COLORS = {

lib/ansible/plugins/callback/skippy.py

@@ -2,8 +2,11 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: skippy
     callback_type: stdout
     requirements:
@@ -14,10 +17,6 @@ DOCUMENTATION:
         - This callback does the same as the default except it does not output skipped host/task/item status
 '''
 
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 from ansible.plugins.callback.default import CallbackModule as CallbackModule_default
 
 

lib/ansible/plugins/callback/slack.py

@@ -2,8 +2,11 @@
 # (C) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: slack
     callback_type: notification
     requirements:
@@ -40,9 +43,6 @@ DOCUMENTATION:
           - section: callback_slack
             key: username
 '''
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 import json
 import os

lib/ansible/plugins/callback/stderr.py

@@ -2,8 +2,11 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: stderr
     callback_type: stdout
     requirements:
@@ -14,9 +17,6 @@ DOCUMENTATION:
         - This is the stderr callback plugin, it behaves like the default callback plugin but sends error output to stderr.
         - Also it does not output skipped host/task/item status
 '''
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 from ansible import constants as C
 from ansible.plugins.callback.default import CallbackModule as CallbackModule_default

lib/ansible/plugins/callback/syslog_json.py

@@ -1,8 +1,11 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-'''
-DOCUMENTATION:
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: syslog_json
     callback_type: notification
     requirements:
@@ -39,10 +42,6 @@ DOCUMENTATION:
             key: syslog_facility
 '''
 
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import os
 import json
 

lib/ansible/plugins/callback/timer.py

@@ -1,7 +1,11 @@
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-'''
-DOCUMENTATION:
+
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: timer
     callback_type: aggregate
     requirements:
@@ -11,9 +15,6 @@ DOCUMENTATION:
     description:
         - This callback just adds total play duration to the play stats.
 '''
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 from datetime import datetime
 

lib/ansible/plugins/callback/tree.py

@@ -1,8 +1,11 @@
 # (c) 2012-2014, Ansible, Inc
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-'''
-DOCUMENTATION:
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     callback: tree
     callback_type: notification
     requirements:
@@ -13,8 +16,6 @@ DOCUMENTATION:
         - "This callback is used by the Ansible (adhoc) command line option `-t|--tree`"
         - This produces a JSON dump of events in a directory, a file for each host, the directory used MUST be passed as a commadn line option.
 '''
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 import os