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
2026-05-06 13:22:48 +00:00 · 2013-06-14 11:53:43 +02:00
parent 39aa5e5eac
commit 5c69918d53
88 changed files with 914 additions and 628 deletions
--- 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"