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

library/system/authorized_key

@@ -66,10 +66,13 @@ author: Brad Olson
 
 EXAMPLES = '''
 # Example using key data from a local file on the management machine
-authorized_key: user=charlie key="{{ lookup('file', '/home/charlie/.ssh/id_rsa.pub') }}"
+- authorized_key: user=charlie key="{{ lookup('file', '/home/charlie/.ssh/id_rsa.pub') }}"
 
 # Using alternate directory locations:
-authorized_key: user=charlie key="{{ lookup('file', '/home/charlie/.ssh/id_rsa.pub') }}" path='/etc/ssh/authorized_keys/charlie' manage_dir=no
+- authorized_key: user=charlie
+                  key="{{ lookup('file', '/home/charlie/.ssh/id_rsa.pub') }}"
+                  path='/etc/ssh/authorized_keys/charlie'
+                  manage_dir=no
 '''
 
 # Makes sure the public key line is present or absent in the user's .ssh/authorized_keys.

library/system/cron

@@ -114,22 +114,29 @@ options:
     default: "no"
     choices: [ "yes", "no" ]
     aliases: []
-
-examples:
-   - code: 'cron: name="check dirs" hour="5,2" job="ls -alh > /dev/null"'
-     description: Ensure a job that runs at 2 and 5 exists. Creates an entry like "* 5,2 * * ls -alh > /dev/null"
-   - code: 'cron: name="an old job" cron job="/some/dir/job.sh" state=absent'
-     description: 'Ensure an old job is no longer present. Removes any job that is preceded by "#Ansible: an old job" in the crontab'
-   - code: 'cron: name="a job for reboot" reboot=yes job="/some/job.sh"'
-     description: 'Creates an entry like "@reboot /some/job.sh"'
-   - code: 'cron: name="yum autoupdate" weekday="2" minute=0 hour=12 user="root" job="YUMINTERACTIVE=0 /usr/sbin/yum-autoupdate" cron_file=ansible_yum-autoupdate'
-
 requirements:
   - cron
 author: Dane Summers
 updates: Mike Grozak
 """
 
+EXAMPLES = '''
+# Ensure a job that runs at 2 and 5 exists.
+# Creates an entry like "* 5,2 * * ls -alh > /dev/null"
+- cron: name="check dirs" hour="5,2" job="ls -alh > /dev/null"
+
+# Ensure an old job is no longer present. Removes any job that is prefixed
+# by "#Ansible: an old job" from the crontab
+- cron: name="an old job" cron job="/some/dir/job.sh" state=absent
+
+# Creates an entry like "@reboot /some/job.sh"
+- cron: name="a job for reboot" reboot=yes job="/some/job.sh"
+
+- cron: name="yum autoupdate" weekday="2" minute=0 hour=12
+        user="root" job="YUMINTERACTIVE=0 /usr/sbin/yum-autoupdate"
+        cron_file=ansible_yum-autoupdate
+'''
+
 import re
 import tempfile
 import os

library/system/facter

@@ -30,14 +30,16 @@ description:
        JSON data that can be useful for inventory purposes.
 version_added: "0.2"
 options: {}
-examples:
-   - code: ansible www.example.net -m facter
-     description: "Example command-line invocation"
 notes: []
 requirements: [ "facter", "ruby-json" ]
 author: Michael DeHaan
 '''
 
+EXAMPLES = '''
+# Example command-line invocation
+ansible www.example.net -m facter
+'''
+
 def main():
     module = AnsibleModule(
         argument_spec = dict()

library/system/filesystem

@@ -44,15 +44,18 @@ options:
   opts:
     description:
     - List of options to be passed to mkfs command.
-examples:
-  - description: Create a ext2 filesystem on /dev/sdb1.
-    code: filesystem fstype=ext2 dev=/dev/sdb1
-  - description: Create a ext4 filesystem on /dev/sdb1 and check disk blocks.
-    code: filesystem fstype=ext4 dev=/dev/sdb1 opts="-cc"
 notes:
   - uses mkfs command
 '''
 
+EXAMPLES = '''
+# Create a ext2 filesystem on /dev/sdb1.
+- filesystem: fstype=ext2 dev=/dev/sdb1
+
+# Create a ext4 filesystem on /dev/sdb1 and check disk blocks.
+- filesystem: fstype=ext4 dev=/dev/sdb1 opts="-cc"
+'''
+
 def main():
     module = AnsibleModule(
         argument_spec = dict(

library/system/group

@@ -48,12 +48,14 @@ options:
         choices: [ "yes", "no" ]
         description:
             - If I(yes), indicates that the group created is a system group.
-examples:
-    - code: "group: name=somegroup state=present"
-      description: Example group command from Ansible Playbooks
 
 '''
 
+EXAMPLES = '''
+# Example group command from Ansible Playbooks
+- group: name=somegroup state=present
+'''
+
 import grp
 import syslog
 import platform

library/system/lvg

@@ -53,19 +53,25 @@ options:
     description:
     - If yes, allows to remove volume group with logical volumes.
     required: false
-examples:
-  - description: Create a volume group on top of /dev/sda1 with physical extent size = 32MB.
-    code: lvg vg=vg.services pvs=/dev/sda1 pesize=32
-  - description: Create or resize a volume group on top of /dev/sdb1 and /dev/sdc5. 
-        If, for example, we already have VG vg.services on top of /dev/sdb1, this VG will be extended by /dev/sdc5.
-        Or if vg.services was created on top of /dev/sda5, we first extend it with /dev/sdb1 and /dev/sdc5, and then reduce by /dev/sda5.
-    code: lvg vg=vg.services pvs=/dev/sdb1,/dev/sdc5
-  - description: Remove a volume group with name vg.services.
-    code: lvg vg=vg.services state=absent
 notes:
   - module does not modify PE size for already present volume group
 '''
 
+EXAMPLES = '''
+# Create a volume group on top of /dev/sda1 with physical extent size = 32MB.
+- lvg:  vg=vg.services pvs=/dev/sda1 pesize=32
+
+# Create or resize a volume group on top of /dev/sdb1 and /dev/sdc5. 
+# If, for example, we already have VG vg.services on top of /dev/sdb1,
+# this VG will be extended by /dev/sdc5.  Or if vg.services was created on
+# top of /dev/sda5, we first extend it with /dev/sdb1 and /dev/sdc5,
+# and then reduce by /dev/sda5.
+- lvg: vg=vg.services pvs=/dev/sdb1,/dev/sdc5
+
+# Remove a volume group with name vg.services.
+- lvg: vg=vg.services state=absent
+'''
+
 def parse_vgs(data):
     vgs = []
     for line in data.splitlines():

library/system/lvol

@@ -44,19 +44,24 @@ options:
     description:
     - Control if the logical volume exists.
     required: false
-examples:
-  - description: Create a logical volume of 512m.
-    code: lvol vg=firefly lv=test size=512
-  - description: Extend the logical volume to 1024m.
-    code: lvol vg=firefly lv=test size=1024
-  - description: Reduce the logical volume to 512m
-    code: lvol vg=firefly lv=test size=512
-  - description: Remove the logical volume.
-    code: lvol vg=firefly lv=test state=absent
 notes:
   - Filesystems on top of the volume are not resized.
 '''
 
+EXAMPLES = '''
+# Create a logical volume of 512m.
+- lvol: vg=firefly lv=test size=512
+
+# Extend the logical volume to 1024m.
+- lvol: vg=firefly lv=test size=1024
+
+# Reduce the logical volume to 512m
+- lvol: vg=firefly lv=test size=512
+
+# Remove the logical volume.
+- lvol: vg=firefly lv=test state=absent
+'''
+
 def parse_lvs(data):
     lvs = []
     for line in data.splitlines():

library/system/mount

@@ -67,18 +67,21 @@ options:
     required: true
     choices: [ "present", "absent", "mounted", "unmounted" ]
     default: null
-examples:
-   - code: "mount: name=/mnt/dvd src=/dev/sr0 fstype=iso9660 opts=ro state=present"
-     description: "Mount DVD read-only"
-   - code: "mount: name=/srv/disk src='LABEL=SOME_LABEL' state=present"
-     description: "Mount up device by label"
-   - code: "mount: name=/home src='UUID=b3e48f45-f933-4c8e-a700-22a159ec9077' opts=noatime state=present"
-     description: "Mount up device by UUID"
      
 notes: []
 requirements: []
 author: Seth Vidal
 '''
+EXAMPLES = '''
+# Mount DVD read-only
+- mount: name=/mnt/dvd src=/dev/sr0 fstype=iso9660 opts=ro state=present
+
+# Mount up device by label
+- mount: name=/srv/disk src='LABEL=SOME_LABEL' state=present
+
+# Mount up device by UUID
+- mount: name=/home src='UUID=b3e48f45-f933-4c8e-a700-22a159ec9077' opts=noatime state=present
+'''
 
 
 def write_fstab(lines, dest):

library/system/ohai

@@ -30,14 +30,16 @@ description:
        I(Ohai) data is a bit more verbose and nested than I(facter).
 version_added: "0.6"
 options: {}
-examples:
-   - code: ansible webservers -m ohai --tree=/tmp/ohaidata
-     description: "Retrieve I(ohai) data from all Web servers and store in one-file per host"
 notes: []
 requirements: [ "ohai" ]
 author: Michael DeHaan
 '''
 
+EXAMPLES = '''
+# Retrieve (ohai) data from all Web servers and store in one-file per host
+ansible webservers -m ohai --tree=/tmp/ohaidata
+'''
+
 def main():
     module = AnsibleModule(
         argument_spec = dict()

library/system/ping

@@ -28,12 +28,14 @@ description:
      contact. It does not make sense in playbooks, but it is useful from
      C(/usr/bin/ansible)
 options: {}
-examples:
-   - code: ansible webservers -m ping
-     description: Test 'webservers' status
 author: Michael DeHaan
 '''
 
+EXAMPLES = '''
+# Test 'webservers' status
+ansible webservers -m ping
+'''
+
 def main():
     module = AnsibleModule(
         argument_spec = dict(

library/system/seboolean

@@ -42,15 +42,17 @@ options:
     required: true
     default: null
     choices: [ 'yes', 'no' ]
-examples:
-   - code: "seboolean: name=httpd_can_network_connect state=yes persistent=yes"
-     description: Set I(httpd_can_network_connect) flag on and keep it persistent across reboots
 notes:
    - Not tested on any debian based system
 requirements: [ ]
 author: Stephen Fromm
 '''
 
+EXAMPLES = '''
+# Set (httpd_can_network_connect) flag on and keep it persistent across reboots
+- seboolean: name=httpd_can_network_connect state=yes persistent=yes
+'''
+
 try:
     import selinux
     HAVE_SELINUX=True

library/system/selinux

@@ -42,16 +42,18 @@ options:
       - path to the SELinux configuration file, if non-standard
     required: false
     default: "/etc/selinux/config"
-examples:
-   - code: "selinux: policy=targeted state=enforcing"
-   - code: "selinux: policy=targeted state=permissive"
-   - code: "selinux: state=disabled"
 notes:
    - Not tested on any debian based system
 requirements: [ libselinux-python ]
 author: Derek Carter <goozbach@friocorte.com>
 '''
 
+EXAMPLES = '''
+- selinux: policy=targeted state=enforcing
+- selinux: policy=targeted state=permissive
+- selinux: state=disabled
+'''
+
 import os
 import re
 import sys

library/system/service

@@ -58,21 +58,29 @@ options:
         description:
         - Additional arguments provided on the command line
         aliases: [ 'args' ]
-examples:
-    - description: Example action to start service httpd, if not running
-      code: "service: name=httpd state=started"
-    - description: Example action to stop service httpd, if running
-      code: "service: name=httpd state=stopped"
-    - description: Example action to restart service httpd, in all cases
-      code: "service: name=httpd state=restarted"
-    - description: Example action to reload service httpd, in all cases
-      code: "service: name=httpd state=reloaded"
-    - description: Example action to enable service httpd, and not touch the running state
-      code: "service: name=httpd enabled=yes"
-    - description: Example action to start service foo, based on running process /usr/bin/foo
-      code: "service: name=foo pattern=/usr/bin/foo state=started"
-    - description: Example action to restart network service for interface eth0
-      code: "service: name=network state=restarted args=eth0"
+'''
+
+EXAMPLES = '''
+# Example action to start service httpd, if not running
+- service: name=httpd state=started
+
+# Example action to stop service httpd, if running
+- service: name=httpd state=stopped
+
+# Example action to restart service httpd, in all cases
+- service: name=httpd state=restarted
+
+# Example action to reload service httpd, in all cases
+- service: name=httpd state=reloaded
+
+# Example action to enable service httpd, and not touch the running state
+- service: name=httpd enabled=yes
+
+# Example action to start service foo, based on running process /usr/bin/foo
+- service: name=foo pattern=/usr/bin/foo state=started
+
+# Example action to restart network service for interface eth0
+- service: name=network state=restarted args=eth0
 '''
 
 import platform

library/system/sysctl

@@ -63,18 +63,24 @@ options:
             - specifies the absolute path to C(sysctl.conf), if not /etc/sysctl.conf
         required: false
         default: /etc/sysctl.conf
-examples:
-    - code: "sysctl: name=vm.swappiness value=5 state=present"
-      description: "Set vm.swappiness to 5 in /etc/sysctl.conf"
-    - code: "sysctl: name=kernel.panic state=absent sysctl_file=/etc/sysctl.conf"
-      description: "Remove kernel.panic entry from /etc/sysctl.conf"
-    - code: "sysctl: name=kernel.panic value=3 sysctl_file=/tmp/test_sysctl.conf check=before reload=no"
-      description: Set kernel.panic to 3 in /tmp/test_sysctl.conf, check if the sysctl key seems writable, but do not reload sysctl, and do not check kernel value after (not needed, because not the real /etc/sysctl.conf updated)
 notes: []
 requirements: []
 author: David "DaviXX" CHANIAL <david.chanial@gmail.com>
 '''
 
+EXAMPLES = '''
+# Set vm.swappiness to 5 in /etc/sysctl.conf
+- sysctl: name=vm.swappiness value=5 state=present
+
+# Remove kernel.panic entry from /etc/sysctl.conf
+- sysctl: name=kernel.panic state=absent sysctl_file=/etc/sysctl.conf
+
+# Set kernel.panic to 3 in /tmp/test_sysctl.conf, check if the sysctl key
+# seems writable, but do not reload sysctl, and do not check kernel value
+# after (not needed, because not the real /etc/sysctl.conf updated)
+- sysctl: name=kernel.panic value=3 sysctl_file=/tmp/test_sysctl.conf check=before reload=no
+'''
+
 # ==============================================================
 
 import os

library/system/user

@@ -158,13 +158,17 @@ options:
             - Set a passphrase for the SSH key.  If no
               passphrase is provided, the SSH key will default to
               having no passphrase.
-examples:
-    - code: 'user: name=johnd comment="John Doe" uid=1040'
-      description: "Add the user 'johnd' with a specific uid and a primary group of 'admin'"
-    - code: "user: name=johnd state=absent remove=yes"
-      description: "Remove the user 'johnd'"
-    - code: 'user: name=jsmith generate_ssh_key=yes ssh_key_bits=2048'
-      description: "Create a 2048-bit SSH key for user jsmith"
+'''
+
+EXAMPLES = '''
+# Add the user 'johnd' with a specific uid and a primary group of 'admin'
+- user: name=johnd comment="John Doe" uid=1040
+
+# Remove the user 'johnd'
+- user: name=johnd state=absent remove=yes
+
+# Create a 2048-bit SSH key for user jsmith
+- user: name=jsmith generate_ssh_key=yes ssh_key_bits=2048
 '''
 
 import os

library/system/zfs

@@ -206,17 +206,24 @@ options:
       - The zoned property.
     required: False
     choices: ['on','off']
-examples:
-  - code: zfs name=rpool/myfs state=present
-    description: Create a new file system called myfs in pool rpool
-  - code: zfs name=rpool/myvol state=present volsize=10M
-    description: Create a new volume called myvol in pool rpool. 
-  - code: zfs name=rpool/myfs@mysnapshot state=present
-    description: Create a snapshot of rpool/myfs file system.
-  - code: zfs name=rpool/myfs2 state=present snapdir=enabled
-    description: Create a new file system called myfs2 with snapdir enabled
 author: Johan Wiren
 '''
+
+EXAMPLES = '''
+# Create a new file system called myfs in pool rpool
+- zfs: name=rpool/myfs state=present
+
+# Create a new volume called myvol in pool rpool. 
+- zfs: name=rpool/myvol state=present volsize=10M
+
+# Create a snapshot of rpool/myfs file system.
+- zfs: name=rpool/myfs@mysnapshot state=present
+
+# Create a new file system called myfs2 with snapdir enabled
+- zfs: name=rpool/myfs2 state=present snapdir=enabled
+'''
+
+
 import os
 
 class Zfs(object):