Merge pull request #3231 from jpmens/docs_more

Docs: consistently format playbook EXAMPLES

library/cloud/ec2

@@ -162,7 +162,7 @@ author: Seth Vidal, Tim Gerla, Lester Wade
 
 EXAMPLES = '''
 # Basic provisioning example
-local_action: 
+- local_action: 
     module: ec2 
     keypair: mykey 
     instance_type: c1.medium 
@@ -172,7 +172,7 @@ local_action:
     count: 3
 
 # Advanced example with tagging and CloudWatch
-local_action: 
+- local_action: 
     module: ec2 
     keypair: mykey 
     group: databases 
@@ -184,7 +184,7 @@ local_action:
     instance_tags: '{"db":"postgres"}' monitoring=yes'
 
 # VPC example
-local_action: 
+- local_action: 
     module: ec2 
     keypair: mykey 
     group_id: sg-1dc53f72 

library/cloud/ec2_vol

@@ -58,21 +58,21 @@ author: Lester Wade
 
 EXAMPLES = '''
 # Simple attachment action
-local_action: 
+- local_action: 
     module: ec2_vol 
     instance: XXXXXX 
     volume_size: 5 
     device_name: sdd
    
 # Playbook example combined with instance launch 
-local_action: 
+- local_action: 
     module: ec2 
     keypair: $keypair 
     image: $image 
     wait: yes 
     count: 3
     register: ec2
-local_action: 
+- local_action: 
     module: ec2_vol 
     instance: ${item.id} 
     volume_size: 5

library/cloud/quantum_floating_ip_associate

@@ -76,7 +76,7 @@ requirements: ["quantumclient", "keystoneclient"]
 
 EXAMPLES = '''
 # Associate a specific floating IP with an Instance
-quantum_floating_ip_associate:
+- quantum_floating_ip_associate:
            state=present
            login_username=admin
            login_password=admin

library/cloud/quantum_router

@@ -79,7 +79,7 @@ requirements: ["quantumclient", "keystoneclient"]
 
 EXAMPLES = '''
 # Creates a router for tenant admin
-quantum_router: state=present
+- quantum_router: state=present
                 login_username=admin
                 login_password=admin
                 login_tenant_name=admin

library/cloud/quantum_router_interface

@@ -79,8 +79,11 @@ 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
+                            login_password=admin
+                            login_tenant_name=admin 
+                            tenant_name=tenant1
+                            router_name=external_route
+                            subnet_name=t1subnet
 '''
 
 

library/cloud/rax

@@ -83,8 +83,8 @@ notes:
 '''
 
 EXAMPLES = '''
-- name: Create a server
-  local_action:
+# Create a server
+- local_action:
      module: rax
      creds_file: ~/.raxpub
      service: cloudservers

library/cloud/virt

@@ -71,7 +71,10 @@ ansible host -m virt -a "name=alpha command=create uri=lxc:///"
 # a playbook example of defining and launching an LXC guest
 tasks:
   - name: define vm
-    virt: name=foo command=define xml="{{ lookup('template', 'container-template.xml.j2') }}" uri=lxc:///
+    virt: name=foo
+          command=define
+          xml="{{ lookup('template', 'container-template.xml.j2') }}"
+          uri=lxc:///
   - name: start vm
     virt: name=foo state=running uri=lxc:///
 '''

library/commands/shell

@@ -45,6 +45,7 @@ author: Michael DeHaan
 '''
 
 EXAMPLES = '''
-# Execute the command in remote shell; stdout goes to the specified file on the remote
+# Execute the command in remote shell; stdout goes to the specified
+# file on the remote
 - shell: somescript.sh >> somelog.txt
 '''

library/database/postgresql_privs

@@ -136,7 +136,7 @@ EXAMPLES = """
 # On database "library":
 # GRANT SELECT, INSERT, UPDATE ON TABLE public.books, public.authors 
 # TO librarian, reader WITH GRANT OPTION
-postgresql_privs: >
+- postgresql_privs: >
     database=library
     state=present
     privs=SELECT,INSERT,UPDATE
@@ -147,7 +147,7 @@ postgresql_privs: >
     grant_option=yes
 
 # Same as above leveraging default values:
-postgresql_privs: >
+- postgresql_privs: >
     db=library
     privs=SELECT,INSERT,UPDATE
     objs=books,authors
@@ -157,7 +157,7 @@ postgresql_privs: >
 # REVOKE GRANT OPTION FOR INSERT ON TABLE books FROM reader 
 # Note that role "reader" will be *granted* INSERT privilege itself if this 
 # isn't already the case (since state=present).
-postgresql_privs: >
+- postgresql_privs: >
     db=library
     state=present
     priv=INSERT
@@ -167,7 +167,7 @@ postgresql_privs: >
 
 # REVOKE INSERT, UPDATE ON ALL TABLES IN SCHEMA public FROM reader
 # "public" is the default schema. This also works for PostgreSQL 8.x.
-postgresql_privs: >
+- postgresql_privs: >
     db=library
     state=absent
     privs=INSERT,UPDATE
@@ -175,7 +175,7 @@ postgresql_privs: >
     role=reader
 
 # GRANT ALL PRIVILEGES ON SCHEMA public, math TO librarian
-postgresql_privs: >
+- postgresql_privs: >
     db=library
     privs=ALL
     type=schema
@@ -184,7 +184,7 @@ postgresql_privs: >
 
 # GRANT ALL PRIVILEGES ON FUNCTION math.add(int, int) TO librarian, reader
 # Note the separation of arguments with colons.
-postgresql_privs: >
+- postgresql_privs: >
     db=library
     privs=ALL
     type=function
@@ -195,7 +195,7 @@ postgresql_privs: >
 # GRANT librarian, reader TO alice, bob WITH ADMIN OPTION
 # Note that group role memberships apply cluster-wide and therefore are not
 # restricted to database "library" here.
-postgresql_privs: >
+- postgresql_privs: >
     db=library
     type=group
     objs=librarian,reader
@@ -205,7 +205,7 @@ postgresql_privs: >
 # GRANT ALL PRIVILEGES ON DATABASE library TO librarian
 # Note that here "db=postgres" specifies the database to connect to, not the
 # database to grant privileges on (which is specified via the "objs" param)
-postgresql_privs: >
+- postgresql_privs: >
     db=postgres
     privs=ALL
     type=database
@@ -215,7 +215,7 @@ postgresql_privs: >
 # GRANT ALL PRIVILEGES ON DATABASE library TO librarian
 # If objs is omitted for type "database", it defaults to the database 
 # to which the connection is established
-postgresql_privs: >
+- postgresql_privs: >
     db=library
     privs=ALL
     type=database

library/files/fetch

@@ -47,14 +47,14 @@ author: Michael DeHaan
 
 EXAMPLES = '''
 # Store file into /tmp/fetched/host.example.com/tmp/somefile
-fetch: src=/tmp/somefile dest=/tmp/fetched
+- fetch: src=/tmp/somefile dest=/tmp/fetched
 
 # Specifying a path directly
-fetch: src=/tmp/somefile dest=/tmp/prefix-{{ ansible_hostname }} flat=yes
+- fetch: src=/tmp/somefile dest=/tmp/prefix-{{ ansible_hostname }} flat=yes
 
 # Specifying a destination path
-fetch: src=/tmp/uniquefile dest=/tmp/special/ flat=yes
+- fetch: src=/tmp/uniquefile dest=/tmp/special/ flat=yes
 
 # Storing in a path relative to the playbook
-fetch: src=/tmp/uniquefile dest=special/prefix-{{ ansible_hostname }} flat=yes
+- fetch: src=/tmp/uniquefile dest=special/prefix-{{ ansible_hostname }} flat=yes
 '''

library/inventory/add_host

@@ -26,8 +26,10 @@ EXAMPLES = '''
 - 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_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}' 
+- add_host: hostname=${new_ip}
+            ansible_ssh_host=${inventory_hostname}
+            ansible_ssh_port=${new_port}' 
 '''

library/messaging/rabbitmq_parameter

@@ -62,7 +62,10 @@ options:
 
 EXAMPLES = """
 # Set the federation parameter 'local_username' to a value of 'guest' (in quotes)
-rabbitmq_parameter: component=federation name=local-username value='"guest"' state=present
+- rabbitmq_parameter: component=federation
+                      name=local-username
+                      value='"guest"'
+                      state=present
 """
 
 class RabbitMqParameter(object):

library/monitoring/airbrake_deployment

@@ -53,7 +53,10 @@ requirements: [ urllib, urllib2 ]
 '''
 
 EXAMPLES = '''
-action: airbrake_deployment token=AAAAAA environment='staging'  user='ansible' revision=4.2
+- airbrake_deployment: token=AAAAAA
+                       environment='staging'
+                       user='ansible'
+                       revision=4.2
 '''
 
 HAS_URLLIB = True

library/monitoring/newrelic_deployment

@@ -69,7 +69,10 @@ requirements: [ urllib, urllib2 ]
 '''
 
 EXAMPLES = '''
-action: newrelic_deployment token=AAAAAA app_name=myapp user='ansible deployment' revision=1.0
+- newrelic_deployment: token=AAAAAA
+                       app_name=myapp
+                       user='ansible deployment'
+                       revision=1.0
 '''
 
 HAS_URLLIB = True

library/monitoring/pagerduty

@@ -66,13 +66,23 @@ notes:
 
 EXAMPLES='''
 # List ongoing maintenance windows.
-pagerduty: name=companyabc user=example@example.com passwd=password123 state=ongoing
+- pagerduty: name=companyabc user=example@example.com passwd=password123 state=ongoing
 
 # Create a 1 hour maintenance window for service FOO123.
-pagerduty: name=companyabc user=example@example.com passwd=password123 state=running service=FOO123"
+- pagerduty: name=companyabc
+             user=example@example.com
+             passwd=password123
+             state=running
+             service=FOO123
 
 # Create a 4 hour maintenance window for service FOO123 with the description "deployment".
-pagerduty: name=companyabc user=example@example.com passwd=password123 state=running service=FOO123 hours=4 desc=deployment"
+- pagerduty: name=companyabc
+             user=example@example.com
+             passwd=password123
+             state=running
+             service=FOO123
+             hours=4
+             desc=deployment
 '''
 
 import json

library/monitoring/pingdom

@@ -52,10 +52,18 @@ notes:
 
 EXAMPLES = '''
 # Pause the check with the ID of 12345.
-pingdom: uid=example@example.com passwd=password123 key=apipassword123 checkid=12345 state=paused
+- pingdom: uid=example@example.com
+           passwd=password123
+           key=apipassword123
+           checkid=12345
+           state=paused
 
 # Unpause the check with the ID of 12345.
-pingdom: uid=example@example.com passwd=password123 key=apipassword123 checkid=12345 state=running
+- pingdom: uid=example@example.com
+           passwd=password123
+           key=apipassword123
+           checkid=12345
+           state=running
 '''
 
 import pingdom

library/network/get_url

@@ -81,7 +81,7 @@ author: Jan-Piet Mens
 '''
 
 EXAMPLES='''
-get_url: url=http://example.com/path/file.conf dest=/etc/foo.conf mode=0440
+- get_url: url=http://example.com/path/file.conf dest=/etc/foo.conf mode=0440
 '''
 
 

library/network/uri

@@ -134,26 +134,26 @@ EXAMPLES = '''
 - action: uri url=http://www.example.com return_content=yes
   register: webpage
 
-  action: fail
+- action: fail
   when_string: '"AWESOME" not in "${webpage.content}"'
 
 
 # Create a JIRA issue.
-action: >
+- 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: > 
+- 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
+  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
+- action: uri url=https://your.form.based.auth.example.com/dashboard.php
             method=GET return_content=yes HEADER_Cookie="${login.set_cookie}"
 '''
 

library/notification/campfire

@@ -43,9 +43,9 @@ author: Adam Garside <adam.garside@gmail.com>
 '''
 
 EXAMPLES = '''
-action: campfire subscription=foo token=12345 room=123 msg="Task completed."
+- campfire: subscription=foo token=12345 room=123 msg="Task completed."
 
-action: campfire subscription=foo token=12345 room=123 notify=loggins
+- campfire: subscription=foo token=12345 room=123 notify=loggins
         msg="Task completed ... with feeling."
 '''
 

library/notification/flowdock

@@ -82,9 +82,18 @@ requirements: [ urllib, urllib2 ]
 '''
 
 EXAMPLES = '''
-action: flowdock type=inbox token=AAAAAA from_address=user@example.com source='my cool app' msg='test from ansible' subject='test subject'
-
-action: flowdock type=chat token=AAAAAA external_user_name=testuser msg='test from ansible' tags=tag1,tag2,tag3
+- flowdock: type=inbox
+            token=AAAAAA
+            from_address=user@example.com
+            source='my cool app'
+            msg='test from ansible'
+            subject='test subject'
+
+- flowdock: type=chat
+            token=AAAAAA
+            external_user_name=testuser
+            msg='test from ansible'
+            tags=tag1,tag2,tag3
 '''
 
 HAS_URLLIB = True

library/notification/hipchat

@@ -53,7 +53,7 @@ author: WAKAYAMA Shirou
 '''
 
 EXAMPLES = '''
-action: hipchat token=AAAAAA room=notify msg="Ansible task finished"
+- hipchat: token=AAAAAA room=notify msg="Ansible task finished"
 '''
 
 # ===========================================

library/notification/irc

@@ -63,13 +63,13 @@ author: Jan-Piet Mens
 '''
 
 EXAMPLES = '''
-action: irc server=irc.example.net channel="#t1" msg="Hello world"
+- irc: server=irc.example.net channel="#t1" msg="Hello world"
 
-local_action: irc port=6669
-              channel="#t1"
-              msg="All finished at {{ ansible_date_time.iso8601 }}"
-              color=red
-              nick=ansibleIRC
+- local_action: irc port=6669
+                channel="#t1"
+                msg="All finished at {{ ansible_date_time.iso8601 }}"
+                color=red
+                nick=ansibleIRC
 '''
 
 # ===========================================

library/notification/jabber

@@ -47,13 +47,24 @@ author: Brian Coca
 
 EXAMPLES = '''
 # send a message to a user
-jabber: user=mybot@chatserver.tld password=secret to=friend@chatserver.tld  msg="Ansible task finished"
+- jabber: user=mybot@example.net
+          password=secret
+          to=friend@example.net
+          msg="Ansible task finished"
 
 # send a message to a room
-jabber: user=mybot@chatserver.tld password=secret to=mychaps@conference.chatserver.tld/ansiblebot  msg="Ansible task finished"
+- jabber: user=mybot@example.net
+          password=secret
+          to=mychaps@conference.example.net/ansiblebot
+          msg="Ansible task finished"
 
 # send a message, specifying the host and port
-jabber user=mybot@chatserver.tld host=talk.chatserver.tld port=5223 password=secret to=mychaps@chatserver.tld  msg="Ansible task finished"
+- jabber user=mybot@example.net
+         host=talk.example.net
+         port=5223
+         password=secret
+         to=mychaps@example.net
+         msg="Ansible task finished"
 '''
 
 import os

library/notification/mail

@@ -103,7 +103,7 @@ options:
 
 EXAMPLES = '''
 # Example playbook sending mail to root
-local_action: mail msg='System ${ansible_hostname} has been sucessfully provisioned.'
+- local_action: mail msg='System ${ansible_hostname} has been sucessfully provisioned.'
 
 # Send e-mail to a bunch of users, attaching files
 - local_action: mail

library/notification/mqtt

@@ -85,7 +85,7 @@ author: Jan-Piet Mens
 '''
 
 EXAMPLES = '''
-local_action: mqtt
+- local_action: mqtt
               topic=service/ansible/{{ ansible_hostname }}
               payload="Hello at {{ ansible_date_time.iso8601 }}"
               qos=0

library/notification/osx_say

@@ -41,7 +41,7 @@ author: Michael DeHaan
 '''
 
 EXAMPLES = '''
-local_action: osx_say msg="{{inventory_hostname}} is all done" voice=Zarvox
+- local_action: osx_say msg="{{inventory_hostname}} is all done" voice=Zarvox
 '''
 
 import subprocess

library/packaging/gem

@@ -60,13 +60,13 @@ author: Johan Wiren
 
 EXAMPLES = '''
 # Installs version 1.0 of vagrant.
-gem: name=vagrant version=1.0 state=present
+- gem: name=vagrant version=1.0 state=present
 
 # Installs latest available version of rake.
-gem: name=rake state=latest
+- gem: name=rake state=latest
 
 # Installs rake version 1.0 from a local gem on disk.
-gem: name=rake gem_source=/path/to/gems/rake-1.0.gem state=present
+- gem: name=rake gem_source=/path/to/gems/rake-1.0.gem state=present
 '''
 
 import re

library/packaging/homebrew

@@ -45,10 +45,10 @@ options:
 notes:  []
 '''
 EXAMPLES = '''
-homebrew: name=foo state=present
-homebrew: name=foo state=present update_homebrew=yes
-homebrew: name=foo state=absent
-homebrew: name=foo,bar state=absent
+- homebrew: name=foo state=present
+- homebrew: name=foo state=present update_homebrew=yes
+- homebrew: name=foo state=absent
+- homebrew: name=foo,bar state=absent
 '''
 
 

library/packaging/rhn_register

@@ -48,13 +48,13 @@ options:
 
 EXAMPLES = '''
 # Unregister system from RHN.
-- code: rhn_register state=absent username=joe_user password=somepass
+- rhn_register: state=absent username=joe_user password=somepass
 
 # Register as user (joe_user) with password (somepass) and auto-subscribe to available content.
-- code: rhn_register state=present username=joe_user password=somepass
+- rhn_register: state=present username=joe_user password=somepass
 
 # Register with activationkey (1-222333444) and enable extended update support.
-- code: rhn_register state=present activationkey=1-222333444 enable_eus=true
+- rhn_register: state=present activationkey=1-222333444 enable_eus=true
 
 # Register as user (joe_user) with password (somepass) against a satellite
 # server specified by (server_url).

library/utilities/debug

@@ -48,11 +48,11 @@ 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"
+- debug: msg="System $inventory_hostname has uuid $ansible_product_uuid"
 
-- action: debug msg="System $inventory_hostname lacks a gateway" fail=yes
+- 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}"
+- debug: msg="System $inventory_hostname has gateway ${ansible_default_ipv4.gateway}"
   only_if: "is_set('${ansible_default_ipv4.gateway}')"
 '''