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
jphalip · Jun 15, 2013 · 5c69918 · 5c69918
1 parent 39aa5e5
commit 5c69918
Show file tree

Hide file tree

Showing 88 changed files with 914 additions and 628 deletions.
diff --git a/docsite/latest/rst/moduledev.rst b/docsite/latest/rst/moduledev.rst
@@ -363,20 +363,17 @@ 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
 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

diff --git 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

diff --git 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

diff --git 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:

diff --git 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:

diff --git 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(

diff --git 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'),

diff --git 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):

diff --git 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
 

diff --git 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