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
2024-09-14 20:13:21 +02:00 · 2013-06-14 11:53:43 +02:00 · 2013-06-14 11:53:43 +02:00 · 5c69918d53
commit 5c69918d53
parent 39aa5e5eac
88 changed files with 914 additions and 628 deletions
--- a/docsite/latest/rst/moduledev.rst
+++ b/docsite/latest/rst/moduledev.rst
@ -363,12 +363,9 @@ Include it in your module file like this::
    module: modulename
    short_description: This is a sentence describing the module
    # ... snip ...
-    examples:
-        - code: modulename opt1=arg1 opt2=arg2
-          description: Optional words describing this example
    '''

-The ``description``, ``notes`` and ``description`` within ``examples``
+The ``description``, and ``notes`` 
 support formatting in some of the output formats (e.g. ``rst``, ``man``).
 These formatting functions are ``U()``, ``M()``, ``I()``, and ``C()``
 for URL, module, italic, and constant-width respectively. It is suggested
@ -376,7 +373,7 @@ to use ``C()`` for file and option names, and ``I()`` when referencing
 parameters; module names should be specifies as ``M(module)``.

 Examples (which typically contain colons, quotes, etc.) are difficult
-to format with YAML, so these can (alternatively, or additionally) be
+to format with YAML, so these must be
 written in plain text in an ``EXAMPLES`` string within the module
 like this::

@ -385,7 +382,7 @@ like this::
    '''

 The ``module_formatter.py`` script and ``ansible-doc(1)`` append the
-``EXAMPLES`` blob after any existing ``examples`` you may have in the
+``EXAMPLES`` blob after any existing (deprecated) ``examples`` you may have in the
 YAML ``DOCUMENTATION`` string.

 Building & Testing
--- a/library/cloud/cloudformation
+++ b/library/cloud/cloudformation
@ -72,19 +72,19 @@ author: James S. Martin
 '''

 EXAMPLES = '''
-  # Basic task example
-  tasks:
-  - name: launch ansible cloudformation example
-    action: cloudformation >
-      stack_name="ansible-cloudformation" state=present
-      region=us-east-1 disable_rollback=yes
-      template=files/cloudformation-example.json
-    args:
-      template_parameters:
-        KeyName: jmartin
-        DiskType: ephemeral
-        InstanceType: m1.small
-        ClusterSize: 3
+# Basic task example
+tasks:
+- name: launch ansible cloudformation example
+  action: cloudformation >
+    stack_name="ansible-cloudformation" state=present
+    region=us-east-1 disable_rollback=yes
+    template=files/cloudformation-example.json
+  args:
+    template_parameters:
+      KeyName: jmartin
+      DiskType: ephemeral
+      InstanceType: m1.small
+      ClusterSize: 3
 '''

 import boto.cloudformation.connection
--- a/library/cloud/glance_image
+++ b/library/cloud/glance_image
@ -85,12 +85,12 @@ options:
     default: None
   is_public:
     description:
-        - Wether the image can be accesed publically
+        - Wether the image can be accessed publicly
     required: false
     default: 'yes'
   copy_from:
     description:
-        - A url from where the image can be downloaded, mutually exculsive with file parameter
+        - A url from where the image can be downloaded, mutually exclusive with file parameter
     required: false
     default: None
   timeout:
@ -103,14 +103,22 @@ options:
        - The path to the file which has to be uploaded, mutually exclusive with copy_from
     required: false
     default: None
-examples:
-  - code: "glance_image: login_username=admin login_password=passme login_tenant_name=admin name=cirros container_format=bare 
-           disk_format=qcow2 state=present copy_from=http:launchpad.net/cirros/trunk/0.3.0/+download/cirros-0.3.0-x86_64-disk.img"
-    description: "Uploads an image from an http url"
 requirements: ["glanceclient", "keystoneclient"]

 '''

+EXAMPLES = '''
+# Upload an image from an HTTP URL
+- glance_image: login_username=admin
+                login_password=passme
+                login_tenant_name=admin
+                name=cirros
+                container_format=bare 
+                disk_format=qcow2
+                state=present
+                copy_from=http:launchpad.net/cirros/trunk/0.3.0/+download/cirros-0.3.0-x86_64-disk.img
+'''
+
 import time
 try:
    import glanceclient
--- a/library/cloud/keystone_user
+++ b/library/cloud/keystone_user
@ -32,7 +32,7 @@ options:
     default: 'http://127.0.0.1:35357/v2.0/'
   user:
     description:
-        - The name of the user that has to added/removed from openstack
+        - The name of the user that has to added/removed from OpenStack
     required: false
     default: None
   password:
@ -65,17 +65,21 @@ options:
        - Indicate desired state of the resource
     choices: ['present', 'absent']
     default: present
-examples:
-   - code: 'keystone_user: tenant=demo tenant_description="Default Tenant"'
-     description: Create a tenant
-   - code: 'keystone_user: user=john tenant=demo password=secrete'
-     description: Create a user
-   - code: 'keystone_user: role=admin user=john tenant=demo'
-     description: Apply the admin role to the john user in the demo tenant
 requirements: [ python-keystoneclient ]
 author: Lorin Hochstein
 '''

+EXAMPLES = '''
+# Create a tenant
+- keystone_user: tenant=demo tenant_description="Default Tenant"
+
+# Create a user
+- keystone_user: user=john tenant=demo password=secrete
+
+# Apply the admin role to the john user in the demo tenant
+- keystone_user: role=admin user=john tenant=demo
+'''
+
 try:
    from keystoneclient.v2_0 import client
 except ImportError:
--- a/library/cloud/nova_compute
+++ b/library/cloud/nova_compute
@ -25,7 +25,7 @@ except ImportError:
 DOCUMENTATION = '''
 ---
 module: nova_compute
-short_description: Create/Delete VM's from OpenStack
+short_description: Create/Delete VMs from OpenStack
 description:
   - Create or Remove virtual machines from Openstack.
 options:
@ -71,41 +71,45 @@ options:
     default: None
   flavor_id:
     description:
-        - The id of the flavor in which the new vm has to be created
+        - The id of the flavor in which the new VM has to be created
     required: false
     default: 1
   key_name:
     description:
-        - The keypair name to be used when creating a vm
+        - The key pair name to be used when creating a VM
     required: false
     default: None
   security_groups:
     description:
-        - The name of the security group to which the vm should be added
+        - The name of the security group to which the VM should be added
     required: false
     default: None
   nics:
     description:
-        - A list of network id's to which the vm's interface should be attached 
+        - A list of network id's to which the VM's interface should be attached 
     required: false
     default: None
   meta:
     description:
-        - A list of key value pairs that should be provided as a metadata to the new vm
+        - A list of key value pairs that should be provided as a metadata to the new VM
     required: false
     default: None
   wait:
     description:
-        - If the module should wait for the vm to be created.
+        - If the module should wait for the VM to be created.
     required: false
     default: 'yes'
   wait_for:
     description:
-        - The amount of time the module should wait for the vm to get into active state
+        - The amount of time the module should wait for the VM to get into active state
     required: false
     default: 180
-examples:
-   - code: "nova_compute:
+requirements: ["novaclient"]
+'''
+
+EXAMPLES = '''
+# Creates a new VM and attaches to a network and passes metadata to the instance
+- nova_compute:
       state: present
       login_username: admin
       login_password: admin
@ -119,10 +123,9 @@ examples:
         - net-id: 34605f38-e52a-25d2-b6ec-754a13ffb723
       meta:
         hostname: test1
-         group: uge_master"
-     description: "Creates a new VM and attaches to a network and passes metadata to the instance"
-requirements: ["novaclient"]
+         group: uge_master
 '''
+
 def _delete_server(module, nova):
    name = None
    try:
--- a/library/cloud/nova_keypair
+++ b/library/cloud/nova_keypair
@ -25,9 +25,9 @@ except ImportError:
 DOCUMENTATION = '''
 ---
 module: nova_keypair
-short_description: Add/Delete keypair from nova
+short_description: Add/Delete key pair from nova
 description:
-   - Add or Remove keypair from nova .
+   - Add or Remove key pair from nova .
 options:
   login_username:
     description:
@ -61,7 +61,7 @@ options:
     default: present
   name:
     description:
-        - Name that has to be given to the keypair
+        - Name that has to be given to the key pair
     required: true
     default: None
   public_key:
@ -70,14 +70,18 @@ options:
     required: false
     default: None

-examples:
-   - code: "nova_keypair: state=present login_username=admin login_password=admin login_tenant_name=admin name=ansible_key
-                          public_key={{ lookup('file','~/.ssh/id_rsa.pub') }}"
-     description: "Creates a keypair with the running users public key"
-   - code: "nova_keypair: state=present login_username=admin login_password=admin login_tenant_name=admin name=ansible_key"
-     description: "Creates a new keypair and the private key returned after the run."
 requirements: ["novaclient"]
 '''
+EXAMPLES = '''
+# Creates a key pair with the running users public key
+- nova_keypair: state=present login_username=admin
+                login_password=admin login_tenant_name=admin name=ansible_key
+                public_key={{ lookup('file','~/.ssh/id_rsa.pub') }}
+
+# Creates a new key pair and the private key returned after the run.
+- nova_keypair: state=present login_username=admin login_password=admin
+                login_tenant_name=admin name=ansible_key
+'''

 def main():
    module = AnsibleModule(
--- a/library/cloud/quantum_floating_ip
+++ b/library/cloud/quantum_floating_ip
@ -27,9 +27,9 @@ except ImportError:
 DOCUMENTATION = '''
 ---
 module: quantum_floating_ip
-short_description: Add/Remove floating ip from an instance
+short_description: Add/Remove floating IP from an instance
 description:
-   - Add or Remove a floating ip to an instance
+   - Add or Remove a floating IP to an instance
 options:
   login_username:
     description:
@ -63,21 +63,24 @@ options:
     default: present
   network_name:
     description:
-        - Name of the nework from which ip has to be assigned to vm. Please make sure the network is an external network 
+        - Name of the network from which IP has to be assigned to VM. Please make sure the network is an external network 
     required: true
     default: None
   instance_name:
     description:
-        - The name of the instance to which the ip address should be assigned
+        - The name of the instance to which the IP address should be assigned
     required: true
     default: None
-examples:
-  - code: "quantum_floating_ip: state=present login_username=admin login_password=admin login_tenant_name=admin 
-                                network_name=external_network instance_name=vm1"
-    description: "Assigns a floating ip to the instance from an external network"
 requirements: ["novaclient", "quantumclient", "keystoneclient"]
 '''

+EXAMPLES = '''
+# Assign a floating ip to the instance from an external network
+- quantum_floating_ip: state=present login_username=admin login_password=admin
+                       login_tenant_name=admin network_name=external_network
+                       instance_name=vm1
+'''
+
 def _get_ksclient(module, kwargs):
    try:
        kclient = ksclient.Client(username=kwargs.get('login_username'),
--- a/library/cloud/quantum_floating_ip_associate
+++ b/library/cloud/quantum_floating_ip_associate
@ -27,9 +27,9 @@ except ImportError:
 DOCUMENTATION = '''
 ---
 module: quantum_floating_ip_associate
-short_description: Associate or disassociate a particular floating ip with an instance
+short_description: Associate or disassociate a particular floating IP with an instance
 description:
-   - Associates or disassociates a specific floating ip with a particular instance
+   - Associates or disassociates a specific floating IP with a particular instance
 options:
   login_username:
     description:
@ -63,7 +63,7 @@ options:
     default: present
   instance_name:
     description:
-        - name of the instance to which the public ip should be assigned
+        - name of the instance to which the public IP should be assigned
     required: true
     default: None
   ip_address:
@ -75,8 +75,14 @@ requirements: ["quantumclient", "keystoneclient"]
 '''

 EXAMPLES = '''
-# Associate a specific floating ip with an Instance
-quantum_floating_ip_associate: state=present login_username=admin login_password=admin login_tenant_name=admin ip_address=1.1.1.1 instance_name=vm1
+# Associate a specific floating IP with an Instance
+quantum_floating_ip_associate:
+           state=present
+           login_username=admin
+           login_password=admin
+           login_tenant_name=admin
+           ip_address=1.1.1.1
+           instance_name=vm1
 '''

 def _get_ksclient(module, kwargs):
--- a/library/cloud/quantum_network
+++ b/library/cloud/quantum_network
@ -94,19 +94,22 @@ options:
        - Wether the state should be marked as up or down
     required: false
     default: true
-examples:
-  - code: "quantum_network: state=present login_username=admin login_password=admin
-                      provider_network_type=gre login_tenant_name=admin
-                      provider_segmentation_id=1  tenant_name=tenant1 name=t1network"
-    description: "Createss a GRE nework with tunnel id of 1 for tenant 1"
-  - code: "quantum_network: state=present login_username=admin login_password=admin
-                      provider_network_type=local login_tenant_name=admin
-                      provider_segmentation_id=1   router_external=yes name=external_network"
-    description: "Creates an external,public network"
 requirements: ["quantumclient", "keystoneclient"]

 '''

+EXAMPLES = '''
+# Creates an external,public network
+- quantum_network: state=present login_username=admin login_password=admin
+                   provider_network_type=gre login_tenant_name=admin
+                   provider_segmentation_id=1  tenant_name=tenant1 name=t1network"
+
+# Createss a GRE nework with tunnel id of 1 for tenant 1
+- quantum_network: state=present login_username=admin login_password=admin
+                   provider_network_type=local login_tenant_name=admin
+                   provider_segmentation_id=1   router_external=yes name=external_network
+'''
+
 _os_keystone = None
 _os_tenant_id = None

--- a/library/cloud/quantum_router
+++ b/library/cloud/quantum_router
@ -79,7 +79,11 @@ requirements: ["quantumclient", "keystoneclient"]

 EXAMPLES = '''
 # Creates a router for tenant admin
-quantum_router: state=present login_username=admin login_password=admin login_tenant_name=admin name=router1"
+quantum_router: state=present
+                login_username=admin
+                login_password=admin
+                login_tenant_name=admin
+                name=router1"
 '''

 _os_keystone = None
--- a/library/cloud/quantum_router_gateway
+++ b/library/cloud/quantum_router_gateway
@ -45,7 +45,7 @@ options:
     default: 'yes'
   auth_url:
     description:
-        - The keystone url for authentication
+        - The keystone URL for authentication
     required: false
     default: 'http://127.0.0.1:35357/v2.0/'
   region_name:
@ -68,13 +68,16 @@ options:
        - Name of the external network which should be attached to the router.
     required: true
     default: None
-examples:
-   - code: "quantum_router_gateway: state=present login_username=admin login_password=admin
-                          login_tenant_name=admin router_name=external_router network_name=external_network"
-     description: "Attaches an external network with a router to allow flow of external traffic"
 requirements: ["quantumclient", "keystoneclient"]
 '''

+EXAMPLES = '''
+# Attach an external network with a router to allow flow of external traffic
+- quantum_router_gateway: state=present login_username=admin login_password=admin
+                          login_tenant_name=admin router_name=external_router
+                          network_name=external_network
+'''
+
 _os_keystone = None
 def _get_ksclient(module, kwargs):
    try:
--- a/library/cloud/quantum_router_interface
+++ b/library/cloud/quantum_router_interface
@ -45,7 +45,7 @@ options:
     default: 'yes'
   auth_url:
     description:
-        - The keystone url for authentication
+        - The keystone URL for authentication
     required: false
     default: 'http://127.0.0.1:35357/v2.0/'
   region_name:
@ -73,13 +73,17 @@ options:
        - Name of the tenant whose subnet has to be attached.
     required: false
     default: None
-examples:
-  - code: "quantum_router_interface: state=present login_username=admin login_password=admin login_tenant_name=admin 
-                                     tenant_name=tenant1 router_name=external_route subnet_name=t1subnet"
-    description: "Attach tenant1's subnet to the external router"
 requirements: ["quantumclient", "keystoneclient"]
 '''

+EXAMPLES = '''
+# Attach tenant1's subnet to the external router
+- quantum_router_interface: state=present login_username=admin
+                            login_password=admin login_tenant_name=admin 
+                            tenant_name=tenant1 router_name=external_route subnet_name=t1subnet
+'''
+
+
 _os_keystone = None
 _os_tenant_id = None

--- a/library/cloud/quantum_subnet
+++ b/library/cloud/quantum_subnet
@ -25,9 +25,9 @@ except ImportError:
 DOCUMENTATION = '''
 ---
 module: quantum_subnet
-short_description: Add/Remove floating ip from an instance
+short_description: Add/Remove floating IP from an instance
 description:
-   - Add or Remove a floating ip to an instance
+   - Add or Remove a floating IP to an instance
 options:
   login_username:
     description:
@ -46,7 +46,7 @@ options:
     default: True
   auth_url:
     description:
-        - The keystone url for authentication
+        - The keystone URL for authentication
     required: false
     default: 'http://127.0.0.1:35357/v2.0/'
   region_name:
@ -61,12 +61,12 @@ options:
     default: present
   network_name:
     description:
-        - Name of the nework to which the subnet should be attached
+        - Name of the network to which the subnet should be attached
     required: true
     default: None
   cidr:
     description:
-        - The cidr representation of the subnet that should be assigned to the subnet
+        - The CIDR representation of the subnet that should be assigned to the subnet
     required: true
     default: None
   tenant_name:
@ -91,22 +91,24 @@ options:
     default: None
   allocation_pool_start:
     description:
-        - From the subnet pool the starting address from which the ip should be allocated
+        - From the subnet pool the starting address from which the IP should be allocated
     required: false
     default: None
   allocation_pool_end:
     description:
-        - From the subnet pool the last ip that should be assigned to the virtual machines
+        - From the subnet pool the last IP that should be assigned to the virtual machines
     required: false
     default: None
-examples:
-  - code: "quantum_subnet: state=present login_username=admin login_password=admin login_tenant_name=admin tenant_name=tenant1
-                     network_name=network1 name=net1subnet cidr=192.168.0.0/24"
-    description: "Create a subnet for a tenant with the specified subnet"
-
 requirements: ["quantum", "keystoneclient"]
 '''

+EXAMPLES = '''
+# Create a subnet for a tenant with the specified subnet
+- quantum_subnet: state=present login_username=admin login_password=admin
+                  login_tenant_name=admin tenant_name=tenant1
+                  network_name=network1 name=net1subnet cidr=192.168.0.0/24"
+'''
+
 _os_keystone   = None
 _os_tenant_id  = None
 _os_network_id = None
--- a/library/cloud/rax
+++ b/library/cloud/rax
@ -19,7 +19,7 @@ DOCUMENTATION = '''
 module: rax
 short_description: create / delete an instance in Rackspace Public Cloud
 description:
-     - creates / deletes Rackspace Public Cloud instances and optionally waits for it to be 'running'.
+     - creates / deletes a Rackspace Public Cloud instance and optionally waits for it to be 'running'.
 version_added: "1.2"
 options:
  service:
@ -74,19 +74,6 @@ options:
    description:
     - how long before wait gives up, in seconds
    default: 300
-examples:
-   - code: |
-           - name: Create a server
-             local_action:
-               module: rax
-               creds_file: ~/.raxpub
-               service: cloudservers
-               name: rax-test1
-               flavor: 5
-               image: b11d9567-e412-4255-96b9-bd63ab23bcfe
-               wait: yes
-               state: present
-     description: "Example from Ansible Playbooks"
 requirements: [ "pyrax" ]
 author: Jesse Keating
 notes:
@ -95,6 +82,19 @@ notes:
  - RAX_REGION defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
 '''

+EXAMPLES = '''
+- name: Create a server
+  local_action:
+     module: rax
+     creds_file: ~/.raxpub
+     service: cloudservers
+     name: rax-test1
+     flavor: 5
+     image: b11d9567-e412-4255-96b9-bd63ab23bcfe
+     wait: yes
+     state: present
+'''
+
 import sys
 import time
 import os
--- a/library/cloud/s3
+++ b/library/cloud/s3
@ -17,9 +17,9 @@
 DOCUMENTATION = '''
 ---
 module: s3
-short_description: idempotent s3 module putting a file into S3. 
+short_description: idempotent S3 module putting a file into S3. 
 description:
-    - This module allows the user to dictate the presence of a given file in an S3 bucket. If or once the key (file) exists in the bucket, it returns a time-expired download url. This module has a dependency on python-boto.
+    - This module allows the user to dictate the presence of a given file in an S3 bucket. If or once the key (file) exists in the bucket, it returns a time-expired download URL. This module has a dependency on python-boto.
 version_added: "1.1"
 options:
  bucket:
@ -41,7 +41,7 @@ options:
    aliases: []
  dest:
    description:
-      - the destination in s3, if different from path
+      - the destination in S3, if different from path
    required: false
    default: null
    aliases: []
@ -53,7 +53,7 @@ options:
    aliases: []
  overwrite:
    description:
-      - force overwrite if a file with the same name already exists. Does not support files uploaded to s3 with multipart upload.
+      - force overwrite if a file with the same name already exists. Does not support files uploaded to S3 with multipart upload.
    required: false
    default: false
    version_added: "1.2"
@ -63,13 +63,11 @@ author: Lester Wade, Ralph Tice

 EXAMPLES = '''
 # Simple PUT operation
-   module: s3 
-   bucket: mybucket 
+- s3: bucket: mybucket 
   path: /path/to/file 
   state: present
 # Force and overwrite if checksums don't match
-   module: s3
-   bucket: mybucket
+- s3: bucket: mybucket
   path: /path/to/file
   state: present
   overwrite: yes
--- a/library/cloud/virt
+++ b/library/cloud/virt
@ -61,8 +61,7 @@ author: Michael DeHaan, Seth Vidal

 EXAMPLES = '''
 # a playbook task line:
-tasks:
-  - virt: name=alpha state=running
+- virt: name=alpha state=running

 # /usr/bin/ansible invocations
 ansible host -m virt -a "name=alpha command=status"
--- a/library/commands/command
+++ b/library/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
--- a/library/commands/raw
+++ b/library/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
+'''
--- a/library/commands/script
+++ b/library/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
+'''
--- a/library/commands/shell
+++ b/library/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
+'''
--- a/library/database/mongodb_user
+++ b/library/database/mongodb_user
@ -67,11 +67,6 @@ options:
        required: false
        default: present
        choices: [ "present", "absent" ]
-examples:
-    - code: "mongodb_user: database=burgers name=bob password=12345 state=present"
-      description: Create 'burgers' database user with name 'bob' and password '12345'.
-    - code: "mongodb_user: database=burgers name=bob state=absent"
-      description: Delete 'burgers' database user with name 'bob'.
 notes:
    - Requires the pymongo Python package on the remote host, version 2.4.2+. This
      can be installed using pip or the OS package manager. @see http://api.mongodb.org/python/current/installation.html
@ -79,6 +74,14 @@ requirements: [ "pymongo" ]
 author: Elliott Foster
 '''

+EXAMPLES = '''
+# Create 'burgers' database user with name 'bob' and password '12345'.
+- mongodb_user: database=burgers name=bob password=12345 state=present
+
+# Delete 'burgers' database user with name 'bob'.
+- mongodb_user: database=burgers name=bob state=absent
+'''
+
 import ConfigParser
 try:
    from pymongo import MongoClient
--- a/library/database/mysql_db
+++ b/library/database/mysql_db
@ -72,9 +72,6 @@ options:
    description:
      - Where to dump/get the C(.sql) file
    required: false
-examples:
-   - code: "mysql_db: db=bobdata state=present"
-     description: Create a new database with name 'bobdata'
 notes:
   - Requires the MySQLdb Python package on the remote host. For Ubuntu, this
     is as easy as apt-get install python-mysqldb. (See M(apt).)
@ -86,6 +83,11 @@ requirements: [ ConfigParser ]
 author: Mark Theunissen
 '''

+EXAMPLES = '''
+# Create a new database with name 'bobdata'
+- mysql_db: db=bobdata state=present
+'''
+
 import ConfigParser
 import os
 try:
--- a/library/database/mysql_user
+++ b/library/database/mysql_user
@ -72,15 +72,6 @@ options:
    required: false
    default: present
    choices: [ "present", "absent" ]
-examples:
-   - code: "mysql_user: name=bob password=12345 priv=*.*:ALL state=present"
-     description: Create database user with name 'bob' and password '12345' with all database privileges
-   - code: "mysql_user: login_user=root login_password=123456 name=sally state=absent"
-     description: Ensure no user named 'sally' exists, also passing in the auth credentials.
-   - code: mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL
-     description: Example privileges string format
-   - code: "mysql_user: name=root password=abc123 login_unix_socket=/var/run/mysqld/mysqld.sock"
-     description: Example using login_unix_socket to connect to server
 notes:
   - Requires the MySQLdb Python package on the remote host. For Ubuntu, this
     is as easy as apt-get install python-mysqldb.
@ -99,9 +90,22 @@ author: Mark Theunissen
 '''

 EXAMPLES = """
+# Create database user with name 'bob' and password '12345' with all database privileges
+- mysql_user: name=bob password=12345 priv=*.*:ALL state=present
+
+# Ensure no user named 'sally' exists, also passing in the auth credentials.
+- mysql_user: login_user=root login_password=123456 name=sally state=absent
+
+# Example privileges string format
+mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL
+
+# Example using login_unix_socket to connect to server
+- mysql_user: name=root password=abc123 login_unix_socket=/var/run/mysqld/mysqld.sock
+
 # Example .my.cnf file for setting the root password
 # Note: don't use quotes around the password, because the mysql_user module
 # will include them in the password but the mysql client will not
+
 [client]
 user=root
 password=n<_665{vS43y
--- a/library/database/postgresql_db
+++ b/library/database/postgresql_db
@ -80,11 +80,6 @@ options:
    required: false
    default: present
    choices: [ "present", "absent" ]
-examples:
-   - code: "postgresql_db: db=acme"
-     description: Create a new database with name C(acme)
-   - code: "postgresql_db: db=acme encoding='UTF-8' lc_collate='de_DE.UTF-8' lc_ctype='de_DE.UTF-8' template='template0'"
-     description: Create a new database with name C(acme) and specific encoding and locale settings. If a template different from C(template0) is specified, encoding and locale settings must match those of the template.
 notes:
   - The default authentication assumes that you are either logging in as or sudo'ing to the C(postgres) account on the host.
   - This module uses I(psycopg2), a Python PostgreSQL database adapter. You must ensure that psycopg2 is installed on
@ -93,6 +88,20 @@ requirements: [ psycopg2 ]
 author: Lorin Hochstein
 '''

+EXAMPLES = '''
+# Create a new database with name "acme"
+- postgresql_db: db=acme
+
+# Create a new database with name "acme" and specific encoding and locale
+# settings. If a template different from "template0" is specified, encoding
+# and locale settings must match those of the template.
+- postgresql_db: db=acme
+                 encoding='UTF-8'
+                 lc_collate='de_DE.UTF-8'
+                 lc_ctype='de_DE.UTF-8'
+                 template='template0'
+'''
+
 try:
    import psycopg2
    import psycopg2.extras
--- a/library/database/postgresql_user
+++ b/library/database/postgresql_user
@ -90,17 +90,6 @@ options:
    required: false
    default: present
    choices: [ "present", "absent" ]
-examples:
-   - code: "postgresql_user: db=acme user=django password=ceec4eif7ya priv=CONNECT/products:ALL"
-     description: Create django user and grant access to database and products table
-   - code: "postgresql_user: user=rails password=secret role_attr_flags=CREATEDB,NOSUPERUSER"
-     description: Create rails user, grant privilege to create other databases and demote rails from super user status
-   - code: "postgresql_user: db=acme user=test priv=ALL/products:ALL state=absent fail_on_user=no"
-     description: Remove test user privileges from acme
-   - code: "postgresql_user: db=test user=test priv=ALL state=absent"
-     description: Remove test user from test database and the cluster
-   - code: INSERT,UPDATE/table:SELECT/anothertable:ALL
-     description: Example privileges string format
 notes:
   - The default authentication assumes that you are either logging in as or
     sudo'ing to the postgres account on the host.
@ -117,6 +106,23 @@ requirements: [ psycopg2 ]
 author: Lorin Hochstein
 '''

+EXAMPLES = '''
+# Create django user and grant access to database and products table
+- postgresql_user: db=acme user=django password=ceec4eif7ya priv=CONNECT/products:ALL
+
+# Create rails user, grant privilege to create other databases and demote rails from super user status
+- postgresql_user: user=rails password=secret role_attr_flags=CREATEDB,NOSUPERUSER
+
+# Remove test user privileges from acme
+- postgresql_user: db=acme user=test priv=ALL/products:ALL state=absent fail_on_user=no
+
+# Remove test user from test database and the cluster
+- postgresql_user: db=test user=test priv=ALL state=absent
+
+# Example privileges string format
+INSERT,UPDATE/table:SELECT/anothertable:ALL
+'''
+
 import re

 try:
--- a/library/database/riak
+++ b/library/database/riak
@ -73,15 +73,18 @@ options:
    default: kv
    aliases: []
    choices: ['kv']
-examples:
-   - code: "riak: command=join target_node=riak@10.1.1.1"
-     description: "Join's a Riak node to another node"
-   - code: "riak: wait_for_handoffs=yes"
-     description: "Wait for handoffs to finish.  Use with async and poll."
-   - code: "riak: wait_for_service=kv"
-     description: "Wait for riak_kv service to startup"
 '''

+EXAMPLES = '''
+# Join's a Riak node to another node
+- riak: command=join target_node=riak@10.1.1.1
+
+# Wait for handoffs to finish.  Use with async and poll.
+- riak: wait_for_handoffs=yes
+
+# Wait for riak_kv service to startup
+- riak: wait_for_service=kv
+'''


 import re
--- a/library/files/assemble
+++ b/library/files/assemble
@ -60,12 +60,14 @@ options:
    description:
      - all arguments accepted by the M(file) module also work here
    required: false
-examples:
-   - code: "assemble: src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf"
-     description: "Example from Ansible Playbooks"
 author: Stephen Fromm
 '''

+EXAMPLES = '''
+# Example from Ansible Playbooks
+- assemble: src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf
+'''
+
 # ===========================================
 # Support method

--- a/library/files/copy
+++ b/library/files/copy
@ -73,19 +73,23 @@ options:
    description:
      - all arguments accepted by the M(file) module also work here
    required: false
-examples:
-   - code: "copy: src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644"
-     description: "Example from Ansible Playbooks"
-   - code: "copy: src=/mine/ntp.conf dest=/etc/ntp.conf owner=root group=root mode=644 backup=yes"
-     description: "Copy a new C(ntp.conf) file into place, backing up the original if it differs from the copied version"
-   - code: "copy: src=/mine/sudoers dest=/etc/sudoers validate='visudo -c %s'"
-     description: "Copy a new C(sudoers) file into place, after passing validation with visudo"
 author: Michael DeHaan
 notes:
   - The "copy" module can't be used to recursively copy directory structures to the target machine. Please see the 
     "Delegation" section of the Advanced Playbooks documentation for a better approach to recursive copies.
 '''

+EXAMPLES = '''
+# Example from Ansible Playbooks
+- copy: src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644
+
+# Copy a new "ntp.conf file into place, backing up the original if it differs from the copied version
+- copy: src=/mine/ntp.conf dest=/etc/ntp.conf owner=root group=root mode=644 backup=yes
+
+# Copy a new "sudoers" file into place, after passing validation with visudo
+- copy: src=/mine/sudoers dest=/etc/sudoers validate='visudo -c %s'
+'''
+
 def main():

    module = AnsibleModule(
--- a/library/files/file
+++ b/library/files/file
@ -120,16 +120,17 @@ options:
    version_added: "1.1"
    description:
      - recursively set the specified file attributes (applies only to state=directory)
-examples:
-   - code: "file: path=/etc/foo.conf owner=foo group=foo mode=0644"
-     description: Example from Ansible Playbooks
-   - code: "file: src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link"
 notes:
    - See also M(copy), M(template), M(assemble)
 requirements: [ ]
 author: Michael DeHaan
 '''

+EXAMPLES = '''
+- file: path=/etc/foo.conf owner=foo group=foo mode=0644
+- file: src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link
+'''
+
 def main():

    # FIXME: pass this around, should not use global
--- a/library/files/ini_file
+++ b/library/files/ini_file
@ -62,15 +62,6 @@ options:
     description:
       - all arguments accepted by the M(file) module also work here
     required: false
-examples:
-   - code: "ini_file: dest=/etc/conf section=drinks option=fav value=lemonade mode=0600 backup=yes"
-     description: Ensure C(fav=lemonade) is in section C([drinks]) in said file
-   - code: |
-           ini_file: dest=/etc/anotherconf
-                     section=drinks
-                     option=temperature
-                     value=cold
-                     backup=yes
 notes:
   - While it is possible to add an I(option) without specifying a I(value), this makes
     no sense.
@ -82,6 +73,16 @@ requirements: [ ConfigParser ]
 author: Jan-Piet Mens
 '''

+EXAMPLES = '''
+# Ensure "fav=lemonade is in section "[drinks]" in specified file
+- ini_file: dest=/etc/conf section=drinks option=fav value=lemonade mode=0600 backup=yes
+
+- ini_file: dest=/etc/anotherconf
+            section=drinks
+            option=temperature
+            value=cold
+            backup=yes
+'''

 import ConfigParser

--- a/library/files/lineinfile
+++ b/library/files/lineinfile
@ -114,19 +114,19 @@ options:
 """

 EXAMPLES = r"""
-   lineinfile: dest=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled
+- lineinfile: dest=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled

-   lineinfile: dest=/etc/sudoers state=absent regexp="^%wheel"
+- lineinfile: dest=/etc/sudoers state=absent regexp="^%wheel"

-   lineinfile: dest=/etc/hosts regexp='^127\.0\.0\.1' line='127.0.0.1 localhost' owner=root group=root mode=0644
+- lineinfile: dest=/etc/hosts regexp='^127\.0\.0\.1' line='127.0.0.1 localhost' owner=root group=root mode=0644

-   lineinfile: dest=/etc/httpd/conf/httpd.conf regexp="^Listen " insertafter="^#Listen " line="Listen 8080"
+- lineinfile: dest=/etc/httpd/conf/httpd.conf regexp="^Listen " insertafter="^#Listen " line="Listen 8080"

-   lineinfile: dest=/etc/services regexp="^# port for http" insertbefore="^www.*80/tcp" line="# port for http by default"
+- lineinfile: dest=/etc/services regexp="^# port for http" insertbefore="^www.*80/tcp" line="# port for http by default"

-   lineinfile: dest=/etc/sudoers state=present regexp='^%wheel' line='%wheel ALL=(ALL) NOPASSWD: ALL'
+- lineinfile: dest=/etc/sudoers state=present regexp='^%wheel' line='%wheel ALL=(ALL) NOPASSWD: ALL'

-   lineinfile: dest=/opt/jboss-as/bin/standalone.conf regexp='^(.*)Xms(\d+)m(.*)$' line='\1Xms${xms}m\3' backrefs=yes
+- lineinfile: dest=/opt/jboss-as/bin/standalone.conf regexp='^(.*)Xms(\d+)m(.*)$' line='\1Xms${xms}m\3' backrefs=yes
 """

 def write_changes(module,lines,dest):
--- a/library/files/template
+++ b/library/files/template
@ -45,11 +45,6 @@ options:
    description:
      - all arguments accepted by the M(file) module also work here
    required: false
-examples:
-   - code: "template: src=/mytemplates/foo.j2 dest=/etc/file.conf owner=bin group=wheel mode=0644"
-     description: "Example from Ansible Playbooks"
-   - code: "action: template src=/mine/sudoers dest=/etc/sudoers validate='visudo -c %s'"
-     description: "Copy a new C(sudoers) file into place, after passing validation with visudo"
 notes:
  - Since Ansible version 0.9, templates are loaded with C(trim_blocks=True).
  - 'You can override jinja2 settings by adding a special header to template file. 
@ -57,3 +52,11 @@ notes:
 requirements: []
 author: Michael DeHaan
 '''
+
+EXAMPLES = '''
+# Example from Ansible Playbooks
+- template: src=/mytemplates/foo.j2 dest=/etc/file.conf owner=bin group=wheel mode=0644
+
+# Copy a new "sudoers file into place, after passing validation with visudo
+- action: template src=/mine/sudoers dest=/etc/sudoers validate='visudo -c %s'
+'''
--- a/library/inventory/add_host
+++ b/library/inventory/add_host
@ -19,11 +19,15 @@ options:
    - The groups to add the hostname to, comma separated.
    required: false
 author: Seth Vidal
-examples:
-  - description: add host to group 'just_created' with variable foo=42
-    code: add_host hostname=${ip_from_ec2} groups=just_created foo=42
-  - description: add a host with a non-standard port local to your machines
-    code: add_host hostname='${new_ip}:${new_port}' 
-  - description: add a host alias that we reach through a tunnel
-    code: add_host hostname=${new_ip} ansible_ssh_host=${inventory_hostname} ansible_ssh_port=${new_port}' 
+'''
+
+EXAMPLES = '''
+# add host to group 'just_created' with variable foo=42
+- add_host: hostname=${ip_from_ec2} groups=just_created foo=42
+
+# add a host with a non-standard port local to your machines
+-  add_host: hostname='${new_ip}:${new_port}' 
+
+# add a host alias that we reach through a tunnel
+-  add_host: hostname=${new_ip} ansible_ssh_host=${inventory_hostname} ansible_ssh_port=${new_port}' 
 '''
--- a/library/inventory/group_by
+++ b/library/inventory/group_by
@ -13,11 +13,13 @@ options:
    - The variables whose values will be used as groups
    required: true
 author: Jeroen Hoekx
-examples:
-  - description: Create groups based on the machine architecture
-    code: group_by key=${ansible_machine}
-  - description: Create groups like 'kvm-host'
-    code: group_by key=${ansible_virtualization_type}-${ansible_virtualization_role}
 notes:
  - Spaces in group names are converted to dashes '-'.
 '''
+
+EXAMPLES = '''
+# Create groups based on the machine architecture
+-  group_by: key=${ansible_machine}
+# Create groups like 'kvm-host'
+-  group_by: key=${ansible_virtualization_type}-${ansible_virtualization_role}
+'''
--- a/library/messaging/rabbitmq_plugin
+++ b/library/messaging/rabbitmq_plugin
@ -46,9 +46,11 @@ options:
    required: false
    default: enabled
    choices: [enabled, disabled]
-examples:
-  - code: rabbitmq_plugin names=rabbitmq_management state=enabled
-    description: Enables the rabbitmq_management plugin
+'''
+
+EXAMPLES = '''
+# Enables the rabbitmq_management plugin
+- rabbitmq_plugin: names=rabbitmq_management state=enabled
 '''

 class RabbitMqPlugins(object):
--- a/library/messaging/rabbitmq_user
+++ b/library/messaging/rabbitmq_user
@ -86,9 +86,17 @@ options:
    required: false
    default: present
    choices: [present, absent]
-examples:
-  - code: rabbitmq_user user=joe password=changeme vhost=/ configure_priv=.* read_priv=.* write_priv=.* state=present
-    description: Add user to server and assign full access control
+'''
+
+EXAMPLES = '''
+# Add user to server and assign full access control
+- rabbitmq_user: user=joe
+                 password=changeme
+                 vhost=/
+                 configure_priv=.*
+                 read_priv=.*
+                 write_priv=.*
+                 state=present
 '''

 class RabbitMqUser(object):
--- a/library/messaging/rabbitmq_vhost
+++ b/library/messaging/rabbitmq_vhost
@ -50,9 +50,11 @@ options:
      - The state of vhost
    default: present
    choices: [present, absent]
-examples:
-   - code: 'rabbitmq_vhost: name=/test state=present'
-     description: Ensure that the vhost /test exists.
+'''
+
+EXAMPLES = '''
+# Ensure that the vhost /test exists.
+- rabbitmq_vhost: name=/test state=present
 '''

 class RabbitMqVhost(object):
--- a/library/monitoring/monit
+++ b/library/monitoring/monit
@ -38,13 +38,15 @@ options:
    required: true
    default: null
    choices: [ "present", "started", "stopped", "restarted", "monitored", "unmonitored", "reloaded" ]
-examples:
-   - code: "monit: name=httpd state=started"
-     description: Manage the state of program I(httpd) to be in I(started) state.
 requirements: [ ]
 author: Darryl Stoflet
 '''

+EXAMPLES = '''
+# Manage the state of program "httpd" to be in "started" state.
+- monit: name=httpd state=started
+'''
+

 def main():
    arg_spec = dict(
--- a/library/monitoring/nagios
+++ b/library/monitoring/nagios
@ -75,31 +75,44 @@ options:

 author: Tim Bielawa
 requirements: [ "Nagios" ]
-examples:
-    - description: set 30 minutes of apache downtime
-      code: "nagios: action=downtime minutes=30 service=httpd host=$inventory_hostname"
-    - description: schedule an hour of HOST downtime
-      code: "nagios: action=downtime minutes=60 service=host host=$inventory_hostname"
-    - description: schedule downtime for ALL services on HOST
-      code: "nagios: action=downtime minutes=45 service=all host=$inventory_hostname"
-    - description: schedule downtime for a few services
-      code: "nagios: action=downtime services=frob,foobar,qeuz host=$inventory_hostname"
-    - description: enable SMART disk alerts
-      code: "nagios: action=enable_alerts service=smart host=$inventory_hostname"
-    - description: "two services at once: disable httpd and nfs alerts"
-      code: "nagios: action=disable_alerts service=httpd,nfs host=$inventory_hostname"
-    - description: disable HOST alerts
-      code: "nagios: action=disable_alerts service=host host=$inventory_hostname"
-    - description: silence ALL alerts
-      code: "nagios: action=silence host=$inventory_hostname"
-    - description: unsilence all alerts
-      code: "nagios: action=unsilence host=$inventory_hostname"
-    - description: SHUT UP NAGIOS
-      code: "nagios: action=silence_nagios"
-    - description: ANNOY ME NAGIOS
-      code: "nagios: action=unsilence_nagios"
-    - description: command something
-      code: "nagios: action=command command='DISABLE_FAILURE_PREDICTION'"
+'''
+
+EXAMPLES = '''
+# set 30 minutes of apache downtime
+- nagios: action=downtime minutes=30 service=httpd host={{ inventory_hostname }}
+
+# schedule an hour of HOST downtime
+- nagios: action=downtime minutes=60 service=host host=$inventory_hostname
+
+# schedule downtime for ALL services on HOST
+- nagios: action=downtime minutes=45 service=all host=$inventory_hostname
+
+# schedule downtime for a few services
+- nagios: action=downtime services=frob,foobar,qeuz host=$inventory_hostname
+
+# enable SMART disk alerts
+- nagios: action=enable_alerts service=smart host=$inventory_hostname
+
+# "two services at once: disable httpd and nfs alerts"
+- nagios: action=disable_alerts service=httpd,nfs host=$inventory_hostname
+
+# disable HOST alerts
+- nagios: action=disable_alerts service=host host=$inventory_hostname
+
+# silence ALL alerts
+- nagios: action=silence host=$inventory_hostname
+
+# unsilence all alerts
+- nagios: action=unsilence host=$inventory_hostname
+
+# SHUT UP NAGIOS
+- nagios: action=silence_nagios
+
+# ANNOY ME NAGIOS
+- nagios: action=unsilence_nagios
+
+# command something
+- nagios: action=command command='DISABLE_FAILURE_PREDICTION'
 '''

 import ConfigParser
--- a/library/net_infrastructure/netscaler
+++ b/library/net_infrastructure/netscaler
@ -73,18 +73,21 @@ options:
    default: server
    choices: ["server", "service"]
    aliases: []
-
-examples:
-   - code: ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass"
-     description: "Disable the server"
-   - code: ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass action=enable"
-     description: "Enable the server"
-   - code: ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass name=local:8080 type=service action=disable"
-     description: "Disable the service local:8080"
 requirements: [ "urllib", "urllib2" ]
 author: Nandor Sivok
 '''

+EXAMPLES = '''
+# Disable the server
+ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass"
+
+# Enable the server
+ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass action=enable"
+
+# Disable the service local:8080
+ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass name=local:8080 type=service action=disable"
+'''
+

 import json
 import urllib
--- a/library/network/slurp
+++ b/library/network/slurp
@ -33,20 +33,20 @@ options:
    required: true
    default: null
    aliases: []
-examples:
-   - code: |
-           ansible host -m slurp -a 'src=/tmp/xx'
-               host | success >> {
-                  "content": "aGVsbG8gQW5zaWJsZSB3b3JsZAo=", 
-                  "encoding": "base64"
-               }
-     description: "Example using C(/usr/bin/ansible)"
 notes:
   - "See also: M(fetch)"
 requirements: []
 author: Michael DeHaan
 '''

+EXAMPLES = '''
+ansible host -m slurp -a 'src=/tmp/xx'
+   host | success >> {
+      "content": "aGVsbG8gQW5zaWJsZSB3b3JsZAo=", 
+      "encoding": "base64"
+   }
+'''
+
 import base64

 def main():
--- a/library/network/uri
+++ b/library/network/uri
@ -120,42 +120,43 @@ options:
    description:
      - all arguments accepted by the M(file) module also work here
    required: false
-examples:
-   - code: "uri: url=http://www.awesome.com"
-     description: "Check that you can connect (GET) to a page and it returns a status 200"
-
-   - code: | 
-           action: uri url=http://www.awesome.com return_content=yes
-           register: webpage
-
-           action: fail
-           when_string: '"AWESOME" not in "${webpage.content}"'
-
-     description: Check that a page returns a status 200 and fail if the word AWESOME is not in the page contents.
-
-   - code: |
-           action: >
-                   uri url=https://your.jira.server.com/rest/api/2/issue/ 
-                   method=POST user=your_username password=your_pass 
-                   body='$FILE(issue.json)' force_basic_auth=yes 
-                   status_code=201 HEADER_Content-Type="application/json"  
-     description: "Create a JIRA issue."
-
-   - code: |
-           action: > 
-                   uri url=https://your.form.based.auth.app.com/index.php 
-                   method=POST body="name=your_username&password=your_password&enter=Sign%20in" 
-                   status_code=302 HEADER_Content-Type="application/x-www-form-urlencoded"
-           register: login
-
-           action: uri url=https://your.form.based.auth.app.com/dashboard.php method=GET return_content=yes HEADER_Cookie="${login.set_cookie}"
-     description: "Login to a form based webpage, then use the cookie that got returned to access the app in later tasks."

 # informational: requirements for nodes
 requirements: [ urlparse, httplib2 ]
 author: Romeo Theriault
 '''

+EXAMPLES = '''
+# Check that you can connect (GET) to a page and it returns a status 200
+- uri: url=http://www.example.com
+
+# Check that a page returns a status 200 and fail if the word AWESOME is not in the page contents.
+- action: uri url=http://www.example.com return_content=yes
+  register: webpage
+
+  action: fail
+  when_string: '"AWESOME" not in "${webpage.content}"'
+
+
+# Create a JIRA issue.
+action: >
+        uri url=https://your.jira.example.com/rest/api/2/issue/ 
+        method=POST user=your_username password=your_pass 
+        body='$FILE(issue.json)' force_basic_auth=yes 
+        status_code=201 HEADER_Content-Type="application/json"  
+
+action: > 
+        uri url=https://your.form.based.auth.examle.com/index.php 
+        method=POST body="name=your_username&password=your_password&enter=Sign%20in" 
+        status_code=302 HEADER_Content-Type="application/x-www-form-urlencoded"
+register: login
+
+# Login to a form based webpage, then use the returned cookie to
+# access the app in later tasks.
+action: uri url=https://your.form.based.auth.example.com/dashboard.php
+            method=GET return_content=yes HEADER_Cookie="${login.set_cookie}"
+'''
+
 HAS_HTTPLIB2 = True
 try:
    import httplib2
--- a/library/notification/mail
+++ b/library/notification/mail
@ -99,24 +99,26 @@ options:
      - The character set of email being sent
    default: 'us-ascii'
    requred: false
-examples:
-    - description: "Example playbook sending mail to root"
-      code: "local_action: mail msg='System ${ansible_hostname} has been sucessfully provisioned.'"
-    - description: Send e-mail to a bunch of users, attaching files
-      code: |
-           - local_action: mail
-                 host='127.0.0.1'
-                 port=2025
-                 subject="Ansible-report"
-                 body="Hello, this is an e-mail. I hope you like it ;-)"
-                 from="jane@example.net (Jane Jolie)"
-                 to="John Doe <j.d@example.org>, Suzie Something <sue@example.com>"
-                 cc="Charlie Root <root@localhost>"
-                 attach="/etc/group /tmp/pavatar2.png"
-                 headers=Reply-To=john@example.com|X-Special="Something or other"
-                 charset=utf8
 """

+EXAMPLES = '''
+# Example playbook sending mail to root
+local_action: mail msg='System ${ansible_hostname} has been sucessfully provisioned.'
+
+# Send e-mail to a bunch of users, attaching files
+- local_action: mail
+                host='127.0.0.1'
+                port=2025
+                subject="Ansible-report"
+                body="Hello, this is an e-mail. I hope you like it ;-)"
+                from="jane@example.net (Jane Jolie)"
+                to="John Doe <j.d@example.org>, Suzie Something <sue@example.com>"
+                cc="Charlie Root <root@localhost>"
+                attach="/etc/group /tmp/pavatar2.png"
+                headers=Reply-To=john@example.com|X-Special="Something or other"
+                charset=utf8
+'''
+
 import os
 import sys
 import smtplib
--- a/library/packaging/apt
+++ b/library/packaging/apt
@ -87,27 +87,38 @@ author: Matthew Williams
 notes:
   - Three of the upgrade modes (C(full), C(safe) and its alias C(yes)) require C(aptitude), otherwise
     C(apt-get) suffices.
-examples:
-    - code: "apt: pkg=foo update_cache=yes"
-      description: Update repositories cache and install C(foo) package
-    - code: "apt: pkg=foo state=absent"
-      description: Remove C(foo) package
-    - code: "apt: pkg=foo state=present"
-      description: Install the package C(foo)
-    - code: "apt: pkg=foo=1.00 state=present"
-      description: Install the version '1.00' of package C(foo)
-    - code: "apt: pkg=nginx state=latest default_release=squeeze-backports update_cache=yes"
-      description: Update the repository cache and update package C(nginx) to latest version using default release C(squeeze-backport)
-    - code: "apt: pkg=openjdk-6-jdk state=latest install_recommends=no"
-      description: Install latest version of C(openjdk-6-jdk) ignoring C(install-reccomends)
-    - code: "apt: upgrade=dist"
-      description: Update all packages to the latest version
-    - code: "apt: update_cache=yes"
-      description: Run the equivalent of C(apt-get update) as a separate step
-    - code: "apt: update_cache=yes cache_valid_time=3600"
-      description: Only run C(update_cache=yes) if the last one is more than more than 3600 seconds ago
 '''

+EXAMPLES = '''
+# Update repositories cache and install "foo" package
+- apt: pkg=foo update_cache=yes
+
+# Remove "foo" package
+- apt: pkg=foo state=absent
+
+# Install the package "foo"
+- apt: pkg=foo state=present
+
+# Install the version '1.00' of package "foo"
+- apt: pkg=foo=1.00 state=present
+
+# Update the repository cache and update package "nginx" to latest version using default release squeeze-backport
+- apt: pkg=nginx state=latest default_release=squeeze-backports update_cache=yes
+
+# Install latest version of "openjdk-6-jdk" ignoring "install-reccomends"
+- apt: pkg=openjdk-6-jdk state=latest install_recommends=no
+
+# Update all packages to the latest version
+- apt: upgrade=dist
+
+# Run the equivalent of "apt-get update" as a separate step
+- apt: update_cache=yes
+
+# Only run "update_cache=yes" if the last one is more than more than 3600 seconds ago
+- apt: update_cache=yes cache_valid_time=3600
+'''
+
+
 import traceback
 # added to stave off future warnings about apt api
 import warnings
--- a/library/packaging/apt_key
+++ b/library/packaging/apt_key
@ -48,17 +48,23 @@ options:
        default: present
        description:
            - used to specify if key is being added or revoked
-examples:
-    - code: "apt_key: url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=present"
-      description: Add an Apt signing key, uses whichever key is at the URL
-    - code: "apt_key: id=473041FA url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=present"
-      description: Add an Apt signing key, will not download if present
-    - code: "apt_key: url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=absent"
-      description: Remove an Apt signing key, uses whichever key is at the URL
-    - code: "apt_key: id=473041FA state=absent"
-      description: Remove a Apt specific signing key
 '''

+EXAMPLES = '''
+# Add an Apt signing key, uses whichever key is at the URL
+- apt_key: url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=present
+
+# Add an Apt signing key, will not download if present
+- apt_key: id=473041FA url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=present
+
+# Remove an Apt signing key, uses whichever key is at the URL
+- apt_key: url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=absent
+
+# Remove a Apt specific signing key
+- apt_key: id=473041FA state=absent
+'''
+
+
 # FIXME: standardize into module_common
 from urllib2 import urlopen, URLError
 from traceback import format_exc
--- a/library/packaging/apt_repository
+++ b/library/packaging/apt_repository
@ -47,14 +47,17 @@ notes:
   - This module cannot be used on Debian Squeeze (Version 6) as there is no C(add-apt-repository) in C(python-software-properties)
   - A bug in C(apt-add-repository) always adds C(deb) and C(deb-src) types for repositories (see the issue on Launchpad U(https://bugs.launchpad.net/ubuntu/+source/software-properties/+bug/987264)), if a repo doesn't have source information (eg MongoDB repo from 10gen) the system will fail while updating repositories.
 author: Matt Wright
-examples:
- code: "apt_repository: repo=ppa:nginx/stable"
-  description: Add nginx stable repository from PPA
- code: "apt_repository: repo='deb http://archive.canonical.com/ubuntu hardy partner'"
-  description: Add specified repository into sources.
 requirements: [ python-apt ]
 '''

+EXAMPLES = '''
+# Add nginx stable repository from PPA
+- apt_repository: repo=ppa:nginx/stable
+
+# Add specified repository into sources.
+- apt_repository: repo='deb http://archive.canonical.com/ubuntu hardy partner'
+'''
+
 import platform

 try:
--- a/library/packaging/easy_install
+++ b/library/packaging/easy_install
@ -57,11 +57,6 @@ options:
        C(pyvenv), C(virtualenv), C(virtualenv2).
    required: false
    default: virtualenv
-examples:
-   - code: "easy_install: name=pip"
-     description: "Examples from Ansible Playbooks"
-   - code: "easy_install: name=flask virtualenv=/webapps/myapp/venv"
-     description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv)"
 notes:
    - Please note that the M(easy_install) module can only install Python
      libraries. Thus this module is not able to remove libraries. It is
@ -73,6 +68,14 @@ requirements: [ "virtualenv" ]
 author: Matt Wright
 '''

+EXAMPLES = '''
+# Examples from Ansible Playbooks
+- easy_install: name=pip
+
+# Install Flast into the specified virtualenv.
+- easy_install: name=flask virtualenv=/webapps/myapp/venv
+'''
+
 def _is_package_installed(module, name, easy_install):
    cmd = '%s --dry-run %s' % (easy_install, name)
    rc, status_stdout, status_stderr = module.run_command(cmd)
--- a/library/packaging/macports
+++ b/library/packaging/macports
@ -46,11 +46,11 @@ options:
 notes:  []
 '''
 EXAMPLES = '''
-macports: name=foo state=present
-macports: name=foo state=present update_cache=yes
-macports: name=foo state=absent
-macports: name=foo state=active
-macports: name=foo state=inactive
+- macports: name=foo state=present
+- macports: name=foo state=present update_cache=yes
+- macports: name=foo state=absent
+- macports: name=foo state=active
+- macports: name=foo state=inactive
 '''


--- a/library/packaging/npm
+++ b/library/packaging/npm
@ -65,21 +65,29 @@ options:
    required: false
    default: present
    choices: [ "present", "absent", "latest" ]
-examples:
-   - code: "npm: name=coffee-script path=/app/location"
-     description: Install I(coffee-script) node.js package.
-   - code: "npm: name=coffee-script version=1.6.1 path=/app/location"
-     description: Install I(coffee-script) node.js package on version 1.6.1.
-   - code: "npm: name=coffee-script global=yes"
-     description: Install I(coffee-script) node.js package globally.
-   - code: "npm: name=coffee-script global=yes state=absent"
-     description: Remove the globally package I(coffee-script).
-   - code: "npm: path=/app/location"
-     description: Install packages based on package.json.
-   - code: "npm: path=/app/location state=latest"
-     description: Update packages based on package.json to their latest version.
-   - code: "npm: path=/app/location executable=/opt/nvm/v0.10.1/bin/npm state=present"
-     description: Install packages based on package.json using the npm installed with nvm v0.10.1.
+'''
+
+EXAMPLES = '''
+description: Install "coffee-script" node.js package.
+- npm: name=coffee-script path=/app/location
+
+description: Install "coffee-script" node.js package on version 1.6.1.
+- npm: name=coffee-script version=1.6.1 path=/app/location
+
+description: Install "coffee-script" node.js package globally.
+- npm: name=coffee-script global=yes
+
+description: Remove the globally package "coffee-script".
+- npm: name=coffee-script global=yes state=absent
+
+description: Install packages based on package.json.
+- npm: path=/app/location
+
+description: Update packages based on package.json to their latest version.
+- npm: path=/app/location state=latest
+
+description: Install packages based on package.json using the npm installed with nvm v0.10.1.
+- npm: path=/app/location executable=/opt/nvm/v0.10.1/bin/npm state=present
 '''

 import os
--- a/library/packaging/openbsd_pkg
+++ b/library/packaging/openbsd_pkg
@ -40,13 +40,17 @@ options:
          - C(present) will make sure the package is installed.
            C(latest) will make sure the latest version of the package is installed.
            C(absent) will make sure the specified package is not installed.
-examples:
-    - description: Make sure nmap is installed
-      code: "openbsd_pkg: name=nmap state=present"
-    - description: Make sure nmap is the latest version
-      code: "openbsd_pkg: name=nmap state=latest"
-    - description: Make sure nmap is not installed
-      code: "openbsd_pkg: name=nmap state=absent"
+'''
+
+EXAMPLES = '''
+# Make sure nmap is installed
+- openbsd_pkg: name=nmap state=present
+
+# Make sure nmap is the latest version
+- openbsd_pkg: name=nmap state=latest
+
+# Make sure nmap is not installed
+- openbsd_pkg: name=nmap state=absent
 '''

 # select whether we dump additional debug info through syslog
--- a/library/packaging/opkg
+++ b/library/packaging/opkg
@ -45,10 +45,10 @@ options:
 notes:  []
 '''
 EXAMPLES = '''
-opkg: name=foo state=present
-opkg: name=foo state=present update_cache=yes
-opkg: name=foo state=absent
-opkg: name=foo,bar state=absent
+- opkg: name=foo state=present
+- opkg: name=foo state=present update_cache=yes
+- opkg: name=foo state=absent
+- opkg: name=foo,bar state=absent
 '''


--- a/library/packaging/pacman
+++ b/library/packaging/pacman
@ -47,16 +47,20 @@ options:

 author: Afterburn
 notes:  []
-examples:
-    - code: "pacman: name=foo state=installed"
-      description: install package foo
-    - code: "pacman: name=foo state=absent"
-      description: remove package foo
-    - code: "pacman: name=foo,bar state=absent"
-      description: remove packages foo and bar 
-    - code: "pacman: name=bar, state=installed, update_cache=yes"
-      description: update the package database (pacman -Syy) and install bar (bar will be the updated if a newer version exists) 
-      
+'''
+
+EXAMPLES = '''
+# Install package foo
+- pacman: name=foo state=installed
+
+# Remove package foo
+- pacman: name=foo state=absent
+
+# Remove packages foo and bar 
+- pacman: name=foo,bar state=absent
+
+# Update the package database (pacman -Syy) and install bar (bar will be the updated if a newer version exists) 
+- pacman: name=bar, state=installed, update_cache=yes
 '''


--- a/library/packaging/pip
+++ b/library/packaging/pip
@ -91,31 +91,41 @@ options:
    required: false
    default: null
    version_added: "1.0"
-examples:
-   - code: "pip: name=flask"
-     description: Install I(flask) python package.
-   - code: "pip: name=flask version=0.8"
-     description: Install I(flask) python package on version 0.8.
-   - code: "pip: name='svn+http://myrepo/svn/MyApp#egg=MyApp'"
-     description: Install I(MyApp) using one of the remote protocols (bzr+,hg+,git+,svn+) or tarballs (zip, gz, bz2) C(pip) supports. You do not have to supply '-e' option in extra_args. For these source names, C(use_mirrors) is ignored and not applicable.
-   - code: "pip: name=flask virtualenv=/my_app/venv"
-     description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv), inheriting none of the globally installed modules"
-   - code: "pip: name=flask virtualenv=/my_app/venv virtualenv_site_packages=yes"
-     description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv), inheriting globally installed modules"
-   - code: "pip: name=flask virtualenv=/my_app/venv virtualenv_command=virtualenv-2.7"
-     description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv), using Python 2.7"
-   - code: "pip: requirements=/my_app/requirements.txt"
-     description: Install specified python requirements.
-   - code: "pip: requirements=/my_app/requirements.txt virtualenv=/my_app/venv"
-     description: Install specified python requirements in indicated I(virtualenv).
-   - code: "pip: requirements=/my_app/requirements.txt extra_args='-i https://example.com/pypi/simple'"
-     description: Install specified python requirements and custom Index URL.
 notes:
   - Please note that virtualenv (U(http://www.virtualenv.org/)) must be installed on the remote host if the virtualenv parameter is specified.
 requirements: [ "virtualenv", "pip" ]
 author: Matt Wright
 '''

+EXAMPLES = '''
+# Install (flask) python package.
+- pip: name=flask
+
+# Install (flask) python package on version 0.8.
+- pip: name=flask version=0.8
+
+# Install (MyApp) using one of the remote protocols (bzr+,hg+,git+,svn+) or tarballs (zip, gz, bz2) (pip) supports. You do not have to supply '-e' option in extra_args. For these source names, (use_mirrors) is ignored and not applicable.
+- pip: name='svn+http://myrepo/svn/MyApp#egg=MyApp'
+
+# Install (Flask) into the specified (virtualenv), inheriting none of the globally installed modules
+- pip: name=flask virtualenv=/my_app/venv
+
+# Install (Flask) into the specified (virtualenv), inheriting globally installed modules
+- pip: name=flask virtualenv=/my_app/venv virtualenv_site_packages=yes
+
+# Install (Flask) into the specified (virtualenv), using Python 2.7
+- pip: name=flask virtualenv=/my_app/venv virtualenv_command=virtualenv-2.7
+
+# Install specified python requirements.
+- pip: requirements=/my_app/requirements.txt
+
+# Install specified python requirements in indicated (virtualenv).
+- pip: requirements=/my_app/requirements.txt virtualenv=/my_app/venv
+
+# Install specified python requirements and custom Index URL.
+- pip: requirements=/my_app/requirements.txt extra_args='-i https://example.com/pypi/simple'
+'''
+

 def _get_full_name(name, version=None):
    if version is None:
--- a/library/packaging/pkgin
+++ b/library/packaging/pkgin
@ -40,13 +40,17 @@ options:
        default: present
 author: Shaun Zinck
 notes:  []
-examples:
-    - code: "pkgin: name=foo state=present"
-      description: install package foo"
-    - code: "pkgin: name=foo state=absent"
-      description: remove package foo
-    - code: "pkgin: name=foo,bar state=absent"
-      description: remove packages foo and bar 
+'''
+
+EXAMPLES = '''
+# install package foo"
+- pkgin: name=foo state=present
+
+# remove package foo
+- pkgin: name=foo state=absent
+
+# remove packages foo and bar 
+- pkgin: name=foo,bar state=absent
 '''


--- a/library/packaging/pkgng
+++ b/library/packaging/pkgng
@ -54,13 +54,14 @@ options:
 author: bleader
 notes:
    - When using pkgsite, be careful that already in cache packages won't be downloaded again.
-examples:
-    - code: "pkgng: name=foo state=present"
-      description: install package foo"
-    - code: "pkgng: name=foo state=absent"
-      description: remove package foo
-    - code: "pkgng: name=foo,bar state=absent"
-      description: remove packages foo and bar 
+'''
+
+EXAMPLES = '''
+# Install package foo
+- pkgng: name=foo state=present
+
+# Remove packages foo and bar 
+- pkgng: name=foo,bar state=absent
 '''


--- a/library/packaging/redhat_subscription
+++ b/library/packaging/redhat_subscription
@ -59,11 +59,17 @@ options:
            - Specify a subscription pool name to consume.  Regular expressions accepted.
        required: False
        default: '^$'
-examples:
-    - code: redhat_subscription action=register username=joe_user password=somepass autosubscribe=true
-      description: Register as user I(joe_user) with password I(somepass) and auto-subscribe to available content.
-    - code: redhat_subscription action=register activationkey=1-222333444 pool='^(Red Hat Enterprise Server|Red Hat Virtualization)$'
-      description: Register with activationkey I(1-222333444) and consume subscriptions matching the names I(Red hat Enterprise Server) and I(Red Hat Virtualization)
+'''
+
+EXAMPLES = '''
+# Register as user (joe_user) with password (somepass) and auto-subscribe to available content.
+- redhat_subscription: action=register username=joe_user password=somepass autosubscribe=true
+
+# Register with activationkey (1-222333444) and consume subscriptions matching
+# the names (Red hat Enterprise Server) and (Red Hat Virtualization)
+- redhat_subscription: action=register
+                       activationkey=1-222333444
+                       pool='^(Red Hat Enterprise Server|Red Hat Virtualization)$'
 '''

 import os
--- a/library/packaging/rhn_channel
+++ b/library/packaging/rhn_channel
@ -43,7 +43,7 @@ options:
 '''

 EXAMPLES = '''
-rhn_channel: name=rhel-x86_64-server-v2vwin-6 sysname=server01 url=https://rhn.redhat.com/rpc/api user=rhnuser password=guessme
+- rhn_channel: name=rhel-x86_64-server-v2vwin-6 sysname=server01 url=https://rhn.redhat.com/rpc/api user=rhnuser password=guessme
 '''

 import xmlrpclib
--- a/library/packaging/rhn_register
+++ b/library/packaging/rhn_register
@ -44,22 +44,31 @@ options:
            - Optionally specify a list of comma-separated channels to subscribe to upon successful registration.
        required: false
        default: []
+'''

-examples:
-    - code: rhn_register state=absent username=joe_user password=somepass
-      description: Unregister system from RHN.
+EXAMPLES = '''
+# Unregister system from RHN.
+- code: rhn_register state=absent username=joe_user password=somepass

-    - code: rhn_register state=present username=joe_user password=somepass
-      description: Register as user I(joe_user) with password I(somepass) and auto-subscribe to available content.
+# Register as user (joe_user) with password (somepass) and auto-subscribe to available content.
+- code: rhn_register state=present username=joe_user password=somepass

-    - code: rhn_register state=present activationkey=1-222333444 enable_eus=true
-      description: Register with activationkey I(1-222333444) and enable extended update support.
+# Register with activationkey (1-222333444) and enable extended update support.
+- code: rhn_register state=present activationkey=1-222333444 enable_eus=true

-    - code: rhn_register state=present username=joe_user password=somepass server_url=https://xmlrpc.my.satellite/XMLRPC
-      description: Register as user I(joe_user) with password I(somepass) against a satellite server specified by I(server_url).
+# Register as user (joe_user) with password (somepass) against a satellite
+# server specified by (server_url).
+- rhn_register:
+    state=present
+    username=joe_user
+    password=somepass
+    server_url=https://xmlrpc.my.satellite/XMLRPC

-    - code: rhn_register state=present username=joe_user password=somepass channels=rhel-x86_64-server-6-foo-1,rhel-x86_64-server-6-bar-1
-      description: Register as user I(joe_user) with password I(somepass) and enable channels I(rhel-x86_64-server-6-foo-1) and I(rhel-x86_64-server-6-bar-1).
+# Register as user (joe_user) with password (somepass) and enable
+# channels (rhel-x86_64-server-6-foo-1) and (rhel-x86_64-server-6-bar-1).
+- rhn_register: state=present username=joe_user
+                password=somepass
+                channels=rhel-x86_64-server-6-foo-1,rhel-x86_64-server-6-bar-1
 '''

 import sys
--- a/library/packaging/svr4pkg
+++ b/library/packaging/svr4pkg
@ -53,15 +53,20 @@ options:
  proxy:
    description:
      - HTTP[s] proxy to be used if C(src) is a URL.
-
-examples:
-  - code: svr4pkg name=CSWcommon src=/tmp/cswpkgs.pkg state=present
-    description: Install a package from an already copied file
-  - code: 'svr4pkg name=CSWpkgutil src=http://get.opencsw.org/now state=present'
-    description: Install a package directly from an http site
-  - code: svr4pkg name=SUNWgnome-sound-recorder state=absent
-    description: Ensure that a package is not installed.
 '''
+
+EXAMPLES = '''
+# Install a package from an already copied file
+- svr4pkg: name=CSWcommon src=/tmp/cswpkgs.pkg state=present
+
+# Install a package directly from an http site
+- svr4pkg: name=CSWpkgutil src=http://get.opencsw.org/now state=present
+
+# Ensure that a package is not installed.
+- svr4pkg: name=SUNWgnome-sound-recorder state=absent
+'''
+
+
 import os
 import tempfile

--- a/library/packaging/yum
+++ b/library/packaging/yum
@ -86,17 +86,18 @@ options:
    default: "no"
    choices: ["yes", "no"]
    aliases: []
-
-examples:
-   - code: yum name=httpd state=latest
-   - code: yum name=httpd state=removed
-   - code: yum name=httpd enablerepo=testing state=installed
 notes: []
 # informational: requirements for nodes
 requirements: [ yum, rpm ]
 author: Seth Vidal
 '''

+EXAMPLES = '''
+- yum: name=httpd state=latest
+- yum: name=httpd state=removed
+- yum: name=httpd enablerepo=testing state=installed
+'''
+
 def_qf = "%{name}-%{version}-%{release}.%{arch}"

 repoquery='/usr/bin/repoquery'
--- a/library/packaging/zypper
+++ b/library/packaging/zypper
@ -60,16 +60,20 @@ options:
        choices: [ "yes", "no" ]
        aliases: []

-examples:
-    - code: "zypper: name=nmap state=present"
-    - code: "zypper: name=nmap state=latest"
-    - code: "zypper: name=nmap state=absent"
 notes: []
 # informational: requirements for nodes
 requirements: [ zypper, rpm ]
 author: Patrick Callahan
 '''

+EXAMPLES = '''
+# Install "nmap"
+- zypper: name=nmap state=present
+
+# Remove the "nmap" package
+- zypper: name=nmap state=absent
+'''
+
 # Function used for getting the name of a currently installed package.
 def get_current_name(m, name):
    cmd = '/bin/rpm -q --qf \'%{NAME}-%{VERSION}\''
--- a/library/source_control/bzr
+++ b/library/source_control/bzr
@ -50,9 +50,11 @@ options:
        description:
            - If C(yes), any modified files in the working
              tree will be discarded.
-examples:
-    - code: "bzr name=bzr+ssh://foosball.example.org/path/to/branch dest=/srv/checkout version=22"
-      description: Example bzr checkout from Ansible Playbooks
+'''
+
+EXAMPLES = '''
+# Example bzr checkout from Ansible Playbooks
+- bzr: name=bzr+ssh://foosball.example.org/path/to/branch dest=/srv/checkout version=22
 '''

 import re
--- a/library/source_control/git
+++ b/library/source_control/git
@ -73,13 +73,19 @@ options:
            - If C(yes), repository will be updated using the supplied
              remote.  Otherwise the repo will be left untouched.
              Prior to 1.2, this was always 'yes' and could not be disabled.
-examples:
-    - code: "git: repo=git://foosball.example.org/path/to/repo.git dest=/srv/checkout version=release-0.22"
-      description: Example git checkout from Ansible Playbooks
-    - code: "git: repo=ssh://git@github.com/mylogin/hello.git dest=/home/mylogin/hello"
-      description: Example read-write git checkout from github
-    - code: "git: repo=git://foosball.example.org/path/to/repo.git dest=/srv/checkout update=no"
-      description: Example just ensuring the repo checkout exists
+'''
+
+EXAMPLES = '''
+# Example git checkout from Ansible Playbooks
+- git: repo=git://foosball.example.org/path/to/repo.git
+       dest=/srv/checkout
+       version=release-0.22
+
+# Example read-write git checkout from github
+- git: repo=ssh://git@github.com/mylogin/hello.git dest=/home/mylogin/hello
+
+# Example just ensuring the repo checkout exists
+- git: repo=git://foosball.example.org/path/to/repo.git dest=/srv/checkout update=no
 '''

 import re
--- a/library/source_control/hg
+++ b/library/source_control/hg
@ -72,13 +72,15 @@ notes:
      C(StrictHostKeyChecking no) in C(.ssh/config) which will accept and authorize the connection
      on behalf of the user. However, if you run as a different user such as setting sudo to True),
      for example, root will not look at the user .ssh/config setting.
-examples:
-    - code: "hg: repo=https://bitbucket.org/user/repo1 dest=/home/user/repo1 revision=stable purge=yes"
-      description: Ensure the current working copy is inside the stable branch and deletes untracked files if any.

 requirements: [ ]
 '''

+EXAMPLES = '''
+# Ensure the current working copy is inside the stable branch and deletes untracked files if any.
+- hg: repo=https://bitbucket.org/user/repo1 dest=/home/user/repo1 revision=stable purge=yes
+'''
+
 def _set_hgrc(hgrc, vals):
    parser = ConfigParser.SafeConfigParser()
    parser.read(hgrc)
--- a/library/source_control/subversion
+++ b/library/source_control/subversion
@ -61,9 +61,11 @@ options:
      - --password parameter passed to svn.
    required: false
    default: null
-examples:
-   - code: "subversion: repo=svn+ssh://an.example.org/path/to/repo dest=/src/checkout"
-     description: Checkout subversion repository to specified folder.
+'''
+
+EXAMPLES = '''
+# Checkout subversion repository to specified folder.
+- subversion: repo=svn+ssh://an.example.org/path/to/repo dest=/src/checkout
 '''

 import re
--- a/library/system/authorized_key
+++ b/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.
--- a/library/system/cron
+++ b/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
--- a/library/system/facter
+++ b/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()
--- a/library/system/filesystem
+++ b/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(
--- a/library/system/group
+++ b/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
--- a/library/system/lvg
+++ b/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():
--- a/library/system/lvol
+++ b/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():
--- a/library/system/mount
+++ b/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):
--- a/library/system/ohai
+++ b/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()
--- a/library/system/ping
+++ b/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(
--- a/library/system/seboolean
+++ b/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
--- a/library/system/selinux
+++ b/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
--- a/library/system/service
+++ b/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
--- a/library/system/sysctl
+++ b/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
--- a/library/system/user
+++ b/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
--- a/library/system/zfs
+++ b/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):
--- a/library/utilities/debug
+++ b/library/utilities/debug
@ -43,13 +43,16 @@ options:
    required: false
    default: "no"
    choices: [ "yes", "no" ]
-examples:
-    - code: |
-        - action: debug msg="System $inventory_hostname has uuid $ansible_product_uuid"
-        - action: debug msg="System $inventory_hostname lacks a gateway" fail=yes
-          only_if: "is_unset('${ansible_default_ipv4.gateway}')"
-        - action: debug msg="System $inventory_hostname has gateway ${ansible_default_ipv4.gateway}"
-          only_if: "is_set('${ansible_default_ipv4.gateway}')"
-      description: "Example that prints the loopback address and gateway for each host"
 author: Dag Wieers
 '''
+
+EXAMPLES = '''
+# Example that prints the loopback address and gateway for each host
+- action: debug msg="System $inventory_hostname has uuid $ansible_product_uuid"
+
+- action: debug msg="System $inventory_hostname lacks a gateway" fail=yes
+  only_if: "is_unset('${ansible_default_ipv4.gateway}')"
+
+- action: debug msg="System $inventory_hostname has gateway ${ansible_default_ipv4.gateway}"
+  only_if: "is_set('${ansible_default_ipv4.gateway}')"
+'''
--- a/library/utilities/fail
+++ b/library/utilities/fail
@ -33,12 +33,12 @@ options:
        fail will simple bail out with a generic message.
    required: false
    default: "'Failed as requested from task'"
-examples:
-    - code: |
-        fail: msg="The system may not be provisioned according to the CMDB status."
-            only_if: "'$cmdb_status' != 'to-be-staged'"
-
-      description: "Example playbook using fail and only_if together"

 author: Dag Wieers
 '''
+
+EXAMPLES = '''
+# Example playbook using fail and only_if together
+- fail: msg="The system may not be provisioned according to the CMDB status."
+  only_if: "'$cmdb_status' != 'to-be-staged'"
+'''
--- a/library/utilities/pause
+++ b/library/utilities/pause
@ -26,11 +26,15 @@ options:
    required: false
    default: null
 author: Tim Bielawa
-examples:
-    - description: Pause for 5 minutes to build app cache.
-      code: "pause: minutes=5"
-    - description: Pause until you can verify updates to an application were successful.
-      code: "pause:"
-    - description: A helpful reminder of what to look out for post-update.
-      code: 'pause: prompt="Make sure org.foo.FooOverload exception is not present"'
+'''
+
+EXAMPLES = '''
+# Pause for 5 minutes to build app cache.
+- pause: minutes=5
+
+# Pause until you can verify updates to an application were successful.
+- pause:
+
+# A helpful reminder of what to look out for post-update.
+- pause: prompt="Make sure org.foo.FooOverload exception is not present"
 '''
--- a/library/utilities/set_fact
+++ b/library/utilities/set_fact
@ -42,10 +42,10 @@ notes:

 EXAMPLES = '''
 # Example setting host facts using key=value pairs
-set_fact: one_fact="something" other_fact="{{ local_var * 2 }}"
+- set_fact: one_fact="something" other_fact="{{ local_var * 2 }}"

 # Example setting host facts using complex arguments
-set_fact:
-  one_fact: something
-  other_fact: "{{ local_var * 2 }}"
+- set_fact:
+     one_fact: something
+     other_fact: "{{ local_var * 2 }}"
 '''
--- a/library/utilities/wait_for
+++ b/library/utilities/wait_for
@ -67,7 +67,7 @@ author: Jeroen Hoekx

 EXAMPLES = '''
 # wait 300 seconds for port 8000 to become open on the host, don't start checking for 10 seconds
-wait_for: port=8000 delay=10"
+- wait_for: port=8000 delay=10"
 '''

 def main():
--- a/library/web_infrastructure/django_manage
+++ b/library/web_infrastructure/django_manage
@ -80,22 +80,22 @@ author: Scott Anderson

 EXAMPLES = """
 # Run cleanup on the application installed in '$django_dir'.
-django_manage: command=cleanup app_path=$django_dir
+- django_manage: command=cleanup app_path=$django_dir

 # Load the $initial_data fixture into the application
-django_manage: command=loaddata app_path=$django_dir fixtures=$initial_data
+- django_manage: command=loaddata app_path=$django_dir fixtures=$initial_data

 #Run syncdb on the application
-django_manage: >
-    command=syncdb 
-    app_path=$django_dir 
-    settings=$settings_app_name 
-    pythonpath=$settings_dir 
-    virtualenv=$virtualenv_dir 
-    database=$mydb
+- django_manage: >
+      command=syncdb 
+      app_path=$django_dir 
+      settings=$settings_app_name 
+      pythonpath=$settings_dir 
+      virtualenv=$virtualenv_dir 
+      database=$mydb

 #Run the SmokeTest test case from the main app. Useful for testing deploys.
-django_manage command=test app_path=django_dir apps=main.SmokeTest
+- django_manage: command=test app_path=django_dir apps=main.SmokeTest
 """


--- a/library/web_infrastructure/supervisorctl
+++ b/library/web_infrastructure/supervisorctl
@ -44,7 +44,7 @@ author: Matt Wright

 EXAMPLES = '''
 # Manage the state of program to be in 'started' state.
-supervisorctl: name=my_app state=started
+- supervisorctl: name=my_app state=started
 '''

 def main():