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/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