DOCS: standardize on EXAMPLES (a.k.a. Docs-JumboPatch JetLag Edition)

  Migrated all examples: in DOCUMENTATION=''' string to standalone EXAMPLES=''' string
  Added deprecation warning to moduledev.rst and remove deprecated example from it
  Fixed up a few typos and uppercased some acronyms.
  add consistency to how EXAMPLES are formatted

4 files changed, 29 insertions, 20 deletions

diff --git a/commands/command b/commands/command
index ad6ed6c1..fb649380 100644
--- a/commands/command
+++ b/commands/command
@@ -65,19 +65,23 @@ options:
     required: false
     default: null
     version_added: "0.9"
-examples:
-   - code: "command: /sbin/shutdown -t now"
-     description: "Example from Ansible Playbooks"
-   - code: "command: /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database"
-     description: "C(creates), C(removes), and C(chdir) can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this."
 notes:
     -  If you want to run a command through the shell (say you are using C(<),
        C(>), C(|), etc), you actually want the M(shell) module instead. The
        M(command) module is much more secure as it's not affected by the user's
        environment.
+    -  " C(creates), C(removes), and C(chdir) can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this."
 author: Michael DeHaan
 '''
 
+EXAMPLES = '''
+# Example from Ansible Playbooks
+- command: /sbin/shutdown -t now
+
+# Run the command if the specified file does not exist
+- command: /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database
+'''
+
 def main():
 
     # the command module is the one ansible module that does not take key=value args
diff --git a/commands/raw b/commands/raw
index 96b495dd..dc4c09d4 100644
--- a/commands/raw
+++ b/commands/raw
@@ -27,9 +27,6 @@ description:
        available. There is no change handler support for this module.
      - This module does not require python on the remote system, much like
        the M(script) module.
-examples:
-    - description: Example from C(/usr/bin/ansible) to bootstrap a legacy python 2.4 host
-      code: "action: raw yum -y install python-simplejson"
 notes:
    -  If you want to execute a command securely and predictably, it may be
       better to use the M(command) module instead. Best practices when writing
@@ -38,3 +35,8 @@ notes:
       judgement.
 author: Michael DeHaan
 '''
+
+EXAMPLES = '''
+# Bootstrap a legacy python 2.4 host
+- raw: yum -y install python-simplejson
+'''
diff --git a/commands/script b/commands/script
index c5e0e0b9..00a1bced 100644
--- a/commands/script
+++ b/commands/script
@@ -4,12 +4,12 @@ DOCUMENTATION = """
 module: script
 short_description: Runs a local script on a remote node after transferring it
 description:
-     - The M(script) module takes the script name followed by a list of
-       space-delimited arguments.
-     - The pathed local script will be transfered to the remote node and then executed.
-     - The given script will be processed through the shell environment on the remote node.
-     - This module does not require python on the remote system, much like
-       the M(raw) module.
+     - "The M(script) module takes the script name followed by a list of
+       space-delimited arguments. "
+     - "The local script at path will be transfered to the remote node and then executed. "
+     - "The given script will be processed through the shell environment on the remote node. "
+     - "This module does not require python on the remote system, much like
+       the M(raw) module. "
 options:
   free_form:
     description:
@@ -17,11 +17,12 @@ options:
     required: true
     default: null
     aliases: []
-examples:
-  - description: "Example from Ansible Playbooks"
-    code: "action: script /some/local/script.sh --some-arguments 1234"
 notes:
   - It is usually preferable to write Ansible modules than pushing scripts. Convert your script to an Ansible module for bonus points!
 author: Michael DeHaan
 """
 
+EXAMPLES = '''
+# Example from Ansible Playbooks
+- script: /some/local/script.sh --some-arguments 1234
+'''
diff --git a/commands/shell b/commands/shell
index 13c6041f..ff57b4d4 100644
--- a/commands/shell
+++ b/commands/shell
@@ -34,9 +34,6 @@ options:
     required: false
     default: null
     version_added: "0.9"
-examples:
-   - code: "shell: somescript.sh >> somelog.txt"
-     description: Execute the command in remote shell
 notes:
    -  If you want to execute a command securely and predictably, it may be
       better to use the M(command) module instead. Best practices when writing
@@ -46,3 +43,8 @@ notes:
 requirements: [ ]
 author: Michael DeHaan
 '''
+
+EXAMPLES = '''
+# Execute the command in remote shell; stdout goes to the specified file on the remote
+- shell: somescript.sh >> somelog.txt
+'''