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/parsing/plugin_docs.py

@@ -24,18 +24,6 @@ def read_docstring(filename, verbose=True, ignore_errors=True):
     Parse DOCUMENTATION from YAML and return the YAML doc or None together with EXAMPLES, as plain text.
     """
 
-    # FIXME: Should refactor this so that we have a docstring parsing
-    # function and a separate variable parsing function
-    # Can have a function one higher that invokes whichever is needed
-    #
-    # Should look roughly like this:
-    # get_plugin_doc(filename, verbose=False)
-    #   documentation = extract_docstring(plugin_ast, identifier, verbose=False)
-    #   if not documentation and not (filter or test):
-    #       documentation = extract_variables(plugin_ast)
-    #   documentation['metadata'] = extract_metadata(plugin_ast)
-    #   return documentation
-
     data = {
         'doc': None,
         'plainexamples': None,
@@ -52,18 +40,7 @@ def read_docstring(filename, verbose=True, ignore_errors=True):
     try:
         b_module_data = open(filename, 'rb').read()
         M = ast.parse(b_module_data)
-        try:
-            display.debug('Attempt first docstring is yaml docs')
-            docstring = yaml.load(M.body[0].value.s)
-            for string in string_to_vars.keys():
-                if string in docstring:
-                    data[string_to_vars[string]] = docstring[string]
-                display.debug('assigned :%s' % string_to_vars[string])
-        except Exception as e:
-            display.debug('failed docstring parsing: %s' % str(e))
 
-        if 'docs' not in data or not data['docs']:
-            display.debug('Fallback to vars parsing')
         for child in M.body:
             if isinstance(child, ast.Assign):
                 for t in child.targets:

lib/ansible/plugins/cache/jsonfile.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 = '''
     cache: jsonfile
     short_description: JSON formatted files.
     description:
@@ -39,10 +42,6 @@ DOCUMENTATION:
         type: integer
 '''
 
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import codecs
 
 try:

lib/ansible/plugins/cache/memcached.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 = '''
     cache: memcached
     short_description: Use memcached DB for cache
     description:
@@ -40,9 +42,6 @@ DOCUMENTATION:
         type: integer
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import collections
 import os
 import time

lib/ansible/plugins/cache/memory.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:
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     cache: memory
     short_description: RAM backed, non persistent
     description:
@@ -14,10 +17,6 @@ DOCUMENTATION:
     author: core team (@ansible-core)
 '''
 
-
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 from ansible.plugins.cache import BaseCacheModule
 
 

lib/ansible/plugins/cache/pickle.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 = '''
     cache: pickle
     short_description: Pickle formatted files.
     description:
@@ -38,10 +41,6 @@ DOCUMENTATION:
             section: defaults
 '''
 
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 try:
     import cPickle as pickle
 except ImportError:

lib/ansible/plugins/cache/redis.py

@@ -1,8 +1,10 @@
 # (c) 2014, Brian Coca, Josh Drake, et al
 # (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 = '''
     cache: redis
     short_description: Use Redis DB for cache
     description:
@@ -37,8 +39,6 @@ DOCUMENTATION:
             section: defaults
         type: integer
 '''
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 import time
 import json

lib/ansible/plugins/cache/yaml.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 = '''
     cache: yaml
     short_description: YAML formatted files.
     description:
@@ -39,10 +42,6 @@ DOCUMENTATION:
         type: integer
 '''
 
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 
 import codecs
 

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
 

lib/ansible/plugins/connection/accelerate.py

@@ -14,8 +14,10 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-"""
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = """
     author: Ansible Core Team
     connection: accelerate
     short_description: Temporary 0mq agent
@@ -27,9 +29,6 @@ DOCUMENTATION:
         alternative: paramiko and ssh with conrol persistence.
 """
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import base64
 import json
 import os

lib/ansible/plugins/connection/buildah.py

@@ -7,8 +7,11 @@
 #
 # Written by: Tomas Tomecek (https://github.com/TomasTomecek)
 
-"""
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+DOCUMENTATION = """
     connection: buildah
     short_description: Interact with an existing buildah container
     description:
@@ -38,8 +41,6 @@ DOCUMENTATION:
 #            - name: remote_user
 """
 
-from __future__ import (absolute_import, division, print_function)
-
 import shlex
 import shutil
 
@@ -57,9 +58,6 @@ except ImportError:
     display = Display()
 
 
-__metaclass__ = type
-
-
 # this _has to be_ named Connection
 class Connection(ConnectionBase):
     """

lib/ansible/plugins/connection/chroot.py

@@ -5,8 +5,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 = """
     author: Maykel Moya <mmoya@speedyrails.com>
     connection: chroot
     short_description: Interact with local chroot
@@ -32,9 +34,6 @@ DOCUMENTATION:
           - name: ansible_executable
 """
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import distutils.spawn
 import os
 import os.path

lib/ansible/plugins/connection/docker.py

@@ -6,8 +6,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 = """
     author:
         - Lorin Hochestein
         - Leendert Brouwer
@@ -37,9 +39,6 @@ DOCUMENTATION:
             - name: ansible_docker_host
 """
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import distutils.spawn
 import os
 import os.path

lib/ansible/plugins/connection/funcd.py

@@ -4,8 +4,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 = """
     author: Michael Scherer (@msherer) <misc@zarb.org>
     connection: funcd
     short_description: Use funcd to connect to target
@@ -23,8 +25,6 @@ DOCUMENTATION:
             - name: ansible_host
             - name: ansible_func_host
 """
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 HAVE_FUNC = False
 try:

lib/ansible/plugins/connection/iocage.py

@@ -5,8 +5,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 = """
     author: Stephan Lohse <dev-github@ploek.org>
     connection: iocage
     short_description: Run tasks in iocage jails
@@ -28,8 +30,6 @@ DOCUMENTATION:
             - name: ansible_user
             - name: ansible_iocage_user
 """
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 import subprocess
 from ansible.plugins.connection.jail import Connection as Jail

lib/ansible/plugins/connection/jail.py

@@ -5,8 +5,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 = """
     author: Ansible Core Team
     connection: jail
     short_description: Run tasks in jails
@@ -29,9 +31,6 @@ DOCUMENTATION:
             - name: ansible_jail_user
 """
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import distutils.spawn
 import os
 import os.path

lib/ansible/plugins/connection/libvirt_lxc.py

@@ -5,8 +5,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 = """
     author: Michael Scherer <misc@zarb.org>
     connection: libvirt_lxc
     short_description: Run tasks in lxc containers via libvirt
@@ -23,9 +25,6 @@ DOCUMENTATION:
             - name: ansible_libvirt_lxc_host
 """
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import distutils.spawn
 import os
 import os.path

lib/ansible/plugins/connection/local.py

@@ -15,8 +15,10 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-'''
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     connection: local
     short_description: execute on controller
     description:
@@ -27,9 +29,6 @@ DOCUMENTATION:
         - The remote user is ignored, the user with which the ansible CLI was executed is used instead.
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import os
 import shutil
 import subprocess

lib/ansible/plugins/connection/lxc.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 = """
     author: Joerg Thalheim <joerg@higgsboson.tk>
     connection: lxc
     short_description: Run tasks in lxc containers via lxc python library
@@ -27,9 +29,6 @@ DOCUMENTATION:
             - name: ansible_lxc_executable
 """
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import os
 import shutil
 import traceback

lib/ansible/plugins/connection/lxd.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 = """
     author: Matt Clay <matt@mystile.com>
     connection: lxd
     short_description: Run tasks in lxc containers via lxc CLI
@@ -27,9 +29,6 @@ DOCUMENTATION:
             - name: ansible_lxd_executable
 """
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import os
 from distutils.spawn import find_executable
 from subprocess import call, Popen, PIPE

lib/ansible/plugins/connection/netconf.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 = """
     author: Ansible Networking Team
     connection: netconf
     short_description: Use netconf to run command on network appliances
@@ -66,8 +68,6 @@ DOCUMENTATION:
 #look_for_keys=C.PARAMIKO_LOOK_FOR_KEYS,
 #allow_agent=self.allow_agent,
 """
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 import os
 import logging

lib/ansible/plugins/connection/network_cli.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 = """
     author: Ansible Networking Team
     connection: network_cli
     short_description: Use network_cli to run command on network appliances
@@ -42,9 +44,6 @@ DOCUMENTATION:
         default: 120
 """
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import json
 import logging
 import re

lib/ansible/plugins/connection/paramiko_ssh.py

@@ -1,8 +1,10 @@
 # (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
 # (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 = """
     author: Ansible Core Team
     connection: paramiko
     short_description: Run tasks via python ssh (paramiko)
@@ -47,8 +49,6 @@ DOCUMENTATION:
 #C.PARAMIKO_PTY
 #C.PARAMIKO_RECORD_HOST_KEYS
 """
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 import warnings
 import os

lib/ansible/plugins/connection/persistent.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 = """
     author: Ansible Core Team
     connection: persistent
     short_description: Use a persistent unix socket for connection
@@ -12,9 +14,6 @@ DOCUMENTATION:
     version_added: "2.3"
 """
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import re
 import os
 import pty

lib/ansible/plugins/connection/saltstack.py

@@ -5,8 +5,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 = """
     author: Michael Scherer <misc@zarb.org>
     connection: saltstack
     short_description: Allow ansible to piggyback on salt minions
@@ -15,9 +17,6 @@ DOCUMENTATION:
     version_added: "2.2"
 """
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import re
 import os
 import pty

lib/ansible/plugins/connection/ssh.py

@@ -4,8 +4,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 = '''
     connection: ssh
     short_description: connect via ssh client binary
     description:
@@ -169,9 +171,6 @@ DOCUMENTATION:
         - {key: scp_if_ssh, section: ssh_connection}
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import errno
 import fcntl
 import hashlib

lib/ansible/plugins/connection/winrm.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 = """
     author: Ansible Core Team
     connection: winrm
     short_description: Run tasks over Microsoft's WinRM
@@ -26,9 +28,6 @@ DOCUMENTATION:
             - name: ansible_winrm_user
 """
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import base64
 import inspect
 import os

lib/ansible/plugins/connection/zone.py

@@ -6,8 +6,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 = """
     author: Ansible Core Team
     connection: zone
     short_description: Run tasks in a zone instance
@@ -24,9 +26,6 @@ DOCUMENTATION:
             - name: ansible_zone_host
 """
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import distutils.spawn
 import os
 import os.path

lib/ansible/plugins/inventory/advanced_host_list.py

@@ -1,24 +1,25 @@
 # 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 = '''
     inventory: advanced_host_list
     version_added: "2.4"
     short_description: Parses a 'host list' with ranges
     description:
         - Parses a host list string as a comma separated values of hosts and supports host ranges.
         - This plugin only applies to inventory sources that are not paths and contain at least one comma.
-EXAMPLES: |
-    # simple range
-    ansible -i 'host[1:10],' -m ping
-
-    # still supports w/o ranges also
-    ansible-playbook -i 'localhost,' play.yml
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+EXAMPLES = '''
+    # simple range
+    # ansible -i 'host[1:10],' -m ping
+
+    # still supports w/o ranges also
+    # ansible-playbook -i 'localhost,' play.yml
+'''
 
 import os
 

lib/ansible/plugins/inventory/constructed.py

@@ -1,8 +1,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 = '''
     name: constructed
     plugin_type: inventory
     version_added: "2.4"
@@ -15,7 +17,10 @@ DOCUMENTATION:
         - Failed expressions will be ignored (assumes vars were missing).
     extends_documentation_fragment:
       - constructed
-EXAMPLES: | # inventory.config file in YAML format
+'''
+
+EXAMPLES = '''
+    # inventory.config file in YAML format
     plugin: comstructed
     compose:
         var_sum: var1 + var2
@@ -42,9 +47,6 @@ EXAMPLES: | # inventory.config file in YAML format
           key: ec2_architecture
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import os
 
 from ansible.errors import AnsibleParserError

lib/ansible/plugins/inventory/host_list.py

@@ -1,27 +1,28 @@
 # Copyright (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-r'''
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = r'''
     inventory: host_list
     version_added: "2.4"
     short_description: Parses a 'host list' string
     description:
         - Parses a host list string as a comma separated values of hosts
         - This plugin only applies to inventory strings that are not paths and contain a comma.
-EXAMPLES: |
-    # define 2 hosts in command line
-    ansible -i '10.10.2.6, 10.10.2.4' -m ping all
-
-    # DNS resolvable names
-    ansible -i 'host1.example.com, host2' -m user -a 'name=me state=absent' all
-
-    # just use localhost
-    ansible-playbook -i 'localhost,' play.yml -c local
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+EXAMPLES = r'''
+    # define 2 hosts in command line
+    # ansible -i '10.10.2.6, 10.10.2.4' -m ping all
+
+    # DNS resolvable names
+    # ansible -i 'host1.example.com, host2' -m user -a 'name=me state=absent' all
+
+    # just use localhost
+    # ansible-playbook -i 'localhost,' play.yml -c local
+'''
 
 import os
 

lib/ansible/plugins/inventory/ini.py

@@ -1,8 +1,9 @@
 # Copyright (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 = '''
     inventory: ini
     version_added: "2.4"
     short_description: Uses an Ansible INI file as inventory source.
@@ -19,8 +20,9 @@ DOCUMENTATION:
     notes:
         - It takes the place of the previously hardcoded INI inventory.
         - To function it requires being whitelisted in configuration.
+'''
 
-EXAMPLES:
+EXAMPLES = '''
   example1: |
       # example cfg file
       [web]
@@ -63,8 +65,6 @@ EXAMPLES:
       host4 # same host as above, but member of 2 groups, will inherit vars from both
             # inventory hostnames are unique
 '''
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 import ast
 import re

lib/ansible/plugins/inventory/openstack.py

@@ -5,8 +5,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 = '''
     name: openstack
     plugin_type: inventory
     short_description: OpenStack inventory source
@@ -84,7 +86,9 @@ DOCUMENTATION:
             description: Add hosts to group based on Jinja2 conditionals.
             type: dictionary
             default: {}
-EXAMPLES:
+'''
+
+EXAMPLES = '''
 # file must be named openstack.yaml or openstack.yml
 # Make the plugin behave like the default behavior of the old script
 simple_config_file:
@@ -93,8 +97,6 @@ simple_config_file:
     expand_hostvars: true
     fail_on_errors: true
 '''
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 import collections
 

lib/ansible/plugins/inventory/script.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 = '''
     inventory: script
     version_added: "2.4"
     short_description: Executes an inventory script that returns JSON
@@ -15,8 +17,6 @@ DOCUMENTATION:
         - It takes the place of the previously hardcoded script inventory.
         - To function it requires being whitelisted in configuration, which is true by default.
 '''
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 import os
 import subprocess

lib/ansible/plugins/inventory/virtualbox.py

@@ -1,8 +1,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 = '''
     name: virtualbox
     plugin_type: inventory
     short_description: virtualbox inventory source
@@ -32,7 +34,9 @@ DOCUMENTATION:
             description: add hosts to group based on Jinja2 conditionals, these also run after query block
             type: dictionary
             default: {}
-EXAMPLES:
+'''
+
+EXAMPLES = '''
 # file must be named vbox.yaml or vbox.yml
 simple_config_file:
     plugin: virtualbox
@@ -42,8 +46,6 @@ simple_config_file:
     compose:
       ansible_connection: ('indows' in vbox_Guest_OS)|ternary('winrm', 'ssh')
 '''
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 import os
 

lib/ansible/plugins/inventory/yaml.py

@@ -1,8 +1,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 = '''
     inventory: yaml
     version_added: "2.4"
     short_description: Uses a specifically YAML file as inventory source.
@@ -20,7 +22,8 @@ DOCUMENTATION:
             description: list of 'valid' extensions for files containing YAML
             type: list
             default: ['.yaml', '.yml', '.json']
-EXAMPLES:
+'''
+EXAMPLES = '''
 all: # keys must be unique, i.e. only one 'hosts' per group
     hosts:
         test1:
@@ -46,9 +49,6 @@ all: # keys must be unique, i.e. only one 'hosts' per group
                 last_var: MYVALUE
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import re
 import os
 

lib/ansible/plugins/lookup/cartesian.py

@@ -14,8 +14,10 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-"""
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = """
     lookup: cartesian
     version_added: "2.1"
     short_description: returns the cartesian product of lists
@@ -26,7 +28,9 @@ DOCUMENTATION:
             description:
                 - a set of lists
             required: True
-EXAMPLES:
+"""
+
+EXAMPLES = """
 
   - name: outputs the cartesian product of the supplied lists
     debug: msg="{{item}}"
@@ -35,15 +39,14 @@ EXAMPLES:
          - "{{list2}}"
   - name: used as lookup changes [1, 2, 3], [a, b] into [1, a], [1, b], [2, a], [2, b], [3, a], [3, b]
     debug: msg="{{ [1,2,3]|lookup('cartesian', [a, b])}}"
+"""
 
-RETURN:
+RETURN = """
   _list:
     description:
       - list of lists composed of elements of the input lists
     type: lists
 """
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 from itertools import product
 

lib/ansible/plugins/lookup/etcd.py

@@ -15,8 +15,10 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-'''
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     author:
         - Jan-Piet Mens (@jpmens)
     lookup: etcd
@@ -47,21 +49,23 @@ DOCUMENTATION:
               - name: ANSIBLE_ETCD_VERSION
             yaml:
               - key: etcd.version
-EXAMPLES:
+'''
+
+EXAMPLES = '''
     - name: "a value from a locally running etcd"
       debug: msg={{ lookup('etcd', 'foo/bar') }}
 
     - name: "a values from a folder on a locally running etcd"
       debug: msg={{ lookup('etcd', 'foo') }}
-RETURN:
+'''
+
+RETURN = '''
     _raw:
         description:
             - list of values associated with input keys
         type: list
         elements: strings
 '''
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 import os
 

lib/ansible/plugins/lookup/mongodb.py

@@ -15,8 +15,12 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-'''
-DOCUMENTATION:
+
+from __future__ import (absolute_import, division, print_function)
+from ansible.module_utils.six import string_types, integer_types
+__metaclass__ = type
+
+DOCUMENTATION = '''
     author: 'Marcos Diez <marcos (at) unitron.com.br>'
     lookup: mongodb
     version_added: "2.3"
@@ -65,7 +69,9 @@ DOCUMENTATION:
         - "Please check https://api.mongodb.org/python/current/api/pymongo/collection.html?highlight=find#pymongo.collection.Collection.find for more detais."
     requirements:
         - pymongo >= 2.4
-EXAMPLES:
+'''
+
+EXAMPLES = '''
 - hosts: all
   gather_facts: false
   vars:
@@ -87,12 +93,8 @@ EXAMPLES:
       with_mongodb: "{{mongodb_parameters}}"
 '''
 
-from __future__ import (absolute_import, division, print_function)
-from ansible.module_utils.six import string_types, integer_types
 import datetime
 
-__metaclass__ = type
-
 try:
     from pymongo import ASCENDING, DESCENDING
     from pymongo.errors import ConnectionFailure

lib/ansible/plugins/strategy/debug.py

@@ -12,8 +12,10 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-'''
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     strategy: debug
     short_description: Executes tasks in interactive debug session.
     description:
@@ -22,9 +24,6 @@ DOCUMENTATION:
     author: Kishin Yagami
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import cmd
 import pprint
 import sys

lib/ansible/plugins/strategy/free.py

@@ -14,8 +14,11 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-'''
-DOCUMENTATION:
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     strategy: free
     short_description: Executes tasks on each host independently
     description:
@@ -25,9 +28,6 @@ DOCUMENTATION:
     version_added: "2.0"
     author: Ansible Core Team
 '''
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 import time
 

lib/ansible/plugins/strategy/linear.py

@@ -14,8 +14,11 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-'''
-DOCUMENTATION:
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     strategy: linear
     short_description: Executes tasks in a linear fashion
     description:
@@ -27,9 +30,6 @@ DOCUMENTATION:
      - This was the default Ansible behaviour before 'strategy plugins' were introduced in 2.0.
     author: Ansible Core Team
 '''
-# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
 
 from ansible.errors import AnsibleError
 from ansible.executor.play_iterator import PlayIterator

lib/ansible/plugins/vars/host_group_vars.py

@@ -15,8 +15,10 @@
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 #############################################
-'''
-DOCUMENTATION:
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
     vars: host_group_vars
     version_added: "2.4"
     short_description: In charge of loading group_vars and host_vars
@@ -41,9 +43,6 @@ DOCUMENTATION:
         type: list
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import os
 from ansible import constants as C
 from ansible.errors import AnsibleParserError