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.

8 files changed, 56 insertions, 48 deletions

diff --git a/lib/ansible/plugins/inventory/advanced_host_list.py b/lib/ansible/plugins/inventory/advanced_host_list.py
index a4c6934351..1783efa961 100644
--- a/lib/ansible/plugins/inventory/advanced_host_list.py
+++ b/lib/ansible/plugins/inventory/advanced_host_list.py
@@ -1,25 +1,26 @@
 # 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: |
+'''
+
+EXAMPLES = '''
     # simple range
-    ansible -i 'host[1:10],' -m ping
+    # ansible -i 'host[1:10],' -m ping
 
     # still supports w/o ranges also
-    ansible-playbook -i 'localhost,' play.yml
+    # ansible-playbook -i 'localhost,' play.yml
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import os
 
 from ansible.errors import AnsibleError, AnsibleParserError
diff --git a/lib/ansible/plugins/inventory/constructed.py b/lib/ansible/plugins/inventory/constructed.py
index 72d112e010..814c67a4f9 100644
--- a/lib/ansible/plugins/inventory/constructed.py
+++ b/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
diff --git a/lib/ansible/plugins/inventory/host_list.py b/lib/ansible/plugins/inventory/host_list.py
index 6b1a8b8104..b9bfa9dbd5 100644
--- a/lib/ansible/plugins/inventory/host_list.py
+++ b/lib/ansible/plugins/inventory/host_list.py
@@ -1,28 +1,29 @@
 # 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: |
+'''
+
+EXAMPLES = r'''
     # define 2 hosts in command line
-    ansible -i '10.10.2.6, 10.10.2.4' -m ping all
+    # 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
+    # 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
+    # ansible-playbook -i 'localhost,' play.yml -c local
 '''
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
-
 import os
 
 from ansible.errors import AnsibleError, AnsibleParserError
diff --git a/lib/ansible/plugins/inventory/ini.py b/lib/ansible/plugins/inventory/ini.py
index a84cdeee19..8033ccf315 100644
--- a/lib/ansible/plugins/inventory/ini.py
+++ b/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
diff --git a/lib/ansible/plugins/inventory/openstack.py b/lib/ansible/plugins/inventory/openstack.py
index 61bb642ea2..a4514b502a 100644
--- a/lib/ansible/plugins/inventory/openstack.py
+++ b/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
 
diff --git a/lib/ansible/plugins/inventory/script.py b/lib/ansible/plugins/inventory/script.py
index a85be8f768..3da241e058 100644
--- a/lib/ansible/plugins/inventory/script.py
+++ b/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
diff --git a/lib/ansible/plugins/inventory/virtualbox.py b/lib/ansible/plugins/inventory/virtualbox.py
index 5d105b984e..9efb74da77 100644
--- a/lib/ansible/plugins/inventory/virtualbox.py
+++ b/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
 
diff --git a/lib/ansible/plugins/inventory/yaml.py b/lib/ansible/plugins/inventory/yaml.py
index 2337fcf333..560d25d96b 100644
--- a/lib/ansible/plugins/inventory/yaml.py
+++ b/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