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