Reformat code: examples consistently

- added terse syntax to modules.rst
 - added description of special variables to template module

apt

@@ -70,17 +70,17 @@ options:
 author: Matthew Williams
 notes: []
 examples:
-    - code: apt pkg=foo update-cache=yes
+    - code: "apt: pkg=foo update-cache=yes"
       description: Update repositories cache and install C(foo) package
-    - code: apt pkg=foo state=removed
+    - code: "apt: pkg=foo state=removed"
       description: Remove C(foo) package
-    - code: apt pkg=foo state=installed
+    - code: "apt: pkg=foo state=installed"
       description: Install the package C(foo)
-    - code: apt pkg=foo=1.00 state=installed
+    - code: "apt: pkg=foo=1.00 state=installed"
       description: Install the version '1.00' of package C(foo)
-    - code: apt pkg=nginx state=latest default-release=squeeze-backports update-cache=yes
+    - code: "apt: pkg=nginx state=latest default-release=squeeze-backports update-cache=yes"
       description: Update the repository cache and update package C(ngnix) to latest version using default release C(squeeze-backport)
-    - code: apt pkg=openjdk-6-jdk state=latest install-recommends=no
+    - code: "apt: pkg=openjdk-6-jdk state=latest install-recommends=no"
       description: Install latest version of C(openjdk-6-jdk) ignoring C(install-recomands)
 '''
 

apt_repository

@@ -48,9 +48,9 @@ notes:
    - 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
+- 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'
+- code: "apt_repository: repo='deb http://archive.canonical.com/ubuntu hardy partner'"
   description: Add specified repository into sources.
 '''
 

assemble

@@ -61,7 +61,7 @@ options:
       - 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
+   - code: "assemble: src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf"
      description: "Example from Ansible Playbooks"
 author: Stephen Fromm
 '''

authorized_key

@@ -47,9 +47,9 @@ options:
     choices: [ "present", "absent" ]
     default: "present"
 examples:
-   - code: authorized_key user=charlie key="ssh-dss ASDF1234L+8BTwaRYr/rycsBF1D8e5pTxEsXHQs4iq+mZdyWqlW++L6pMiam1A8yweP+rKtgjK2httVS6GigVsuWWfOd7/sdWippefq74nppVUELHPKkaIOjJNN1zUHFoL/YMwAAAEBALnAsQN10TNGsRDe5arBsW8cTOjqLyYBcIqgPYTZW8zENErFxt7ij3fW3Jh/sCpnmy8rkS7FyK8ULX0PEy/2yDx8/5rXgMIICbRH/XaBy9Ud5bRBFVkEDu/r+rXP33wFPHjWjwvHAtfci1NRBAudQI/98DbcGQw5HmE89CjgZRo5ktkC5yu/8agEPocVjdHyZr7PaHfxZGUDGKtGRL2QzRYukCmWo1cZbMBHcI5FzImvTHS9/8B3SATjXMPgbfBuEeBwuBK5EjL+CtHY5bWs9kmYjmeo0KfUMH8hY4MAXDoKhQ7DhBPIrcjS5jPtoGxIREZjba67r6/P2XKXaCZH6Fc= charlie@example.org 2011-01-17"
+   - code: 'authorized_key: user=charlie key="ssh-dss ASDF1234L+8BTwaRYr/rycsBF1D8e5pTxEsXHQs4iq+mZdyWqlW++L6pMiam1A8yweP+rKtgjK2httVS6GigVsuWWfOd7/sdWippefq74nppVUELHPKkaIOjJNN1zUHFoL/YMwAAAEBALnAsQN10TNGsRDe5arBsW8cTOjqLyYBcIqgPYTZW8zENErFxt7ij3fW3Jh/sCpnmy8rkS7FyK8ULX0PEy/2yDx8/5rXgMIICbRH/XaBy9Ud5bRBFVkEDu/r+rXP33wFPHjWjwvHAtfci1NRBAudQI/98DbcGQw5HmE89CjgZRo5ktkC5yu/8agEPocVjdHyZr7PaHfxZGUDGKtGRL2QzRYukCmWo1cZbMBHcI5FzImvTHS9/8B3SATjXMPgbfBuEeBwuBK5EjL+CtHY5bWs9kmYjmeo0KfUMH8hY4MAXDoKhQ7DhBPIrcjS5jPtoGxIREZjba67r6/P2XKXaCZH6Fc= charlie@example.org 2011-01-17"'
      description: "Example from Ansible Playbooks"
-   - code: "authorized_key user=charlie key=$FILE(/home/charlie/.ssh/id_rsa.pub)"
+   - code: "authorized_key: user=charlie key=$FILE(/home/charlie/.ssh/id_rsa.pub)"
      description: "Shorthand available in Ansible 0.8 and later"
 author: Brad Olson
 '''

command

@@ -61,9 +61,9 @@ options:
     required: false
     default: null
 examples:
-   - code: command /sbin/shutdown -t now
+   - code: "command: /sbin/shutdown -t now"
      description: "Example from Ansible Playbooks"
-   - code: command /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database
+   - code: "command: /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database"
      description: "I(creates), I(removes), and I(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(<),

copy

@@ -53,9 +53,9 @@ options:
       - 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
+   - 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
+   - 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"
 author: Michael DeHaan
 '''

cron

@@ -99,9 +99,9 @@ options:
     default: "*"
     aliases: []
 examples:
-   - code: cron name="check dirs" hour="5,2" job="ls -alh > /dev/null"
+   - 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
+   - 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'
 requirements: cron
 author: Dane Summers

easy_install

@@ -40,9 +40,9 @@ options:
     required: false
     default: null
 examples:
-   - code: easy_install name=pip
+   - code: "easy_install: name=pip"
      description: "Examples from Ansible Playbooks"
-   - code: easy_install name=flask virtualenv=/webapps/myapp/venv
+   - 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

fail

@@ -41,7 +41,7 @@ options:
     default: 1
 examples:
     - code: |
-        action: fail msg="The system may not be provisioned according to the CMDB status." rc=100
+        fail: msg="The system may not be provisioned according to the CMDB status." rc=100
             only_if: "'$cmdb_status' != 'to-be-staged'"
 
       description: "Example playbook using fail and only_if together"

fetch

@@ -26,7 +26,7 @@ options:
     required: true
     default: null
 examples:
-   - code: fetch src=/var/log/messages dest=/home/logtree
+   - code: "fetch: src=/var/log/messages dest=/home/logtree"
      description: "Example from Ansible Playbooks"
 requirements: []
 author: Michael DeHaan

file

@@ -114,9 +114,9 @@ options:
       - accepts only C(default) as value. This will restore a file's SELinux context
         in the policy. Does nothing if no default value is available.
 examples:
-   - code: file path=/etc/foo.conf owner=foo group=foo mode=0644
+   - 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
+   - 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: [ ]

fireball

@@ -54,7 +54,7 @@ examples:
            - hosts: devservers
                  connection: fireball
                  tasks:
-                     - action: command /usr/bin/anything
+                     - command: /usr/bin/anything
      description: "This example playbook has two plays: the first launches I(fireball) mode on all hosts via SSH, and the second actually starts using I(fireball) node for subsequent management over the fireball interface"
 notes:
     - See the advanced playbooks chapter for more about using fireball mode.

get_url

@@ -60,7 +60,7 @@ options:
       - all arguments accepted by the M(file) module also work here
     required: false
 examples:
-   - code: get_url url=http://example.com/path/file.conf dest=/etc/foo.conf mode=0440
+   - code: "get_url: url=http://example.com/path/file.conf dest=/etc/foo.conf mode=0440"
      description: "Example from Ansible Playbooks"
 notes:
     - This module doesn't yet support configuration for proxies or passwords.

git

@@ -56,7 +56,7 @@ options:
               repository will be discarded.  Prior to 0.7, 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
+    - 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
 '''
 

group

@@ -49,7 +49,7 @@ options:
         description:
             - If I(yes), indicates that the group created is a system group.
 examples:
-    - code: group name=somegroup state=present
+    - code: "group: name=somegroup state=present"
       description: Example group command from Ansible Playbooks
 
 '''

ini_file

@@ -63,10 +63,10 @@ options:
        - 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=true
+   - code: "ini_file: dest=/etc/conf section=drinks option=fav value=lemonade mode=0600 backup=true"
      description: Ensure C(fav=lemonade) is in section C([drinks]) in said file
    - code: |
-           ini_file dest=/etc/anotherconf
+           ini_file: dest=/etc/anotherconf
                      section=drinks
                      option=temperature
                      value=cold

lineinfile

@@ -72,8 +72,8 @@ options:
        - Create a backup file including the timestamp information so you can
          get the original file back if you somehow clobbered it incorrectly.
 examples:
-   - code: lineinfile dest=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled
-   - code: lineinfile dest=/etc/sudoers state=absent regexp="^%wheel"
+   - code: "lineinfile: dest=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled"
+   - code: 'lineinfile: dest=/etc/sudoers state=absent regexp="^%wheel"'
 '''
 
 def present(module, dest, regexp, line, insertafter, backup):

mount

@@ -68,7 +68,7 @@ options:
     choices: [ "present", "absent", "mounted", "unmounted" ]
     default: null
 examples:
-   - code: mount name=/mnt/dvd src=/dev/sr0 fstype=iso9660 opts=ro
+   - code: "mount: name=/mnt/dvd src=/dev/sr0 fstype=iso9660 opts=ro"
      description: "Mount DVD read-only"
 notes: []
 requirements: []

mysql_db

@@ -68,7 +68,7 @@ options:
       - Where to dump/get the .sql file
     required: true
 examples:
-   - code: mysql_db db=bobdata state=present
+   - 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

mysql_user

@@ -68,9 +68,9 @@ options:
     default: present
     choices: [ "present", "absent" ]
 examples:
-   - code: mysql_user name=bob password=12345 priv=*.*:ALL state=present
+   - 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
+   - 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

nagios

@@ -68,21 +68,21 @@ author: Tim Bielawa
 requirements: [ "Nagios" ]
 examples:
     - description: set 30 minutes of apache downtime
-      code: nagios action=downtime minutes=30 service=httpd host=$inventory_hostname
+      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
+      code: "nagios: action=downtime minutes=60 service=host host=$inventory_hostname"
     - description: schedule downtime for a few services
-      code: nagios action=downtime services=frob,foobar,qeuz host=$inventory_hostname
+      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
+      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
+      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
+      code: "nagios: action=disable_alerts service=host host=$inventory_hostname"
     - description: silence ALL alerts
-      code: nagios action=silence host=$inventory_hostname
+      code: "nagios: action=silence host=$inventory_hostname"
     - description: unsilence all alerts
-      code: nagios action=unsilence host=$inventory_hostname
+      code: "nagios: action=unsilence host=$inventory_hostname"
 '''
 
 import ConfigParser

pause

@@ -28,9 +28,9 @@ options:
 author: Tim Bielawa
 examples:
     - description: Pause for 5 minutes to build app cache.
-      code: pause minutes=5
+      code: "pause: minutes=5"
     - description: Pause until you can verify updates to an application were successful.
-      code: pause
+      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"
+      code: 'pause: prompt="Make sure org.foo.FooOverload exception is not present"'
 '''

pip

@@ -54,15 +54,15 @@ options:
     default: present
     choices: [ "present", "absent", "latest" ]
 examples:
-   - code: pip name=flask
+   - code: "pip: name=flask"
      description: Install I(flask) python package.
-   - code: pip name=flask version=0.8
+   - code: "pip: name=flask version=0.8"
      description: Install I(flask) python package on version 0.8.
-   - code: pip name=flask virtualenv=/srv/webapps/my_app/venv
+   - code: "pip: name=flask virtualenv=/srv/webapps/my_app/venv"
      description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv)"
-   - code: pip requirements=/srv/webapps/my_app/src/requirements.txt
+   - code: "pip: requirements=/srv/webapps/my_app/src/requirements.txt"
      description: Install specified python requirements.
-   - code: pip requirements=/srv/webapps/my_app/src/requirements.txt virtualenv=/srv/webapps/my_app/venv
+   - code: "pip: requirements=/srv/webapps/my_app/src/requirements.txt virtualenv=/srv/webapps/my_app/venv"
      description: Install specified python requirements in indicated virtualenv.
 notes:
    - Please note that U(http://www.virtualenv.org/, virtualenv) must be installed on the remote host if the virtualenv parameter is specified.

postgresql_db

@@ -56,7 +56,7 @@ options:
     default: present
     choices: [ "present", "absent" ]
 examples:
-   - code: postgresql_db db=acme
+   - code: "postgresql_db: db=acme"
      description: Create a new database with name 'acme'
 notes:
    - The default authentication assumes that you are either logging in as or sudo'ing to the postgres account on the host.

postgresql_user

@@ -91,13 +91,13 @@ options:
     default: present
     choices: [ "present", "absent" ]
 examples:
-   - code: postgresql_user db=acme user=django password=ceec4eif7ya priv=CONNECT/products:ALL
+   - 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
+   - 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
+   - 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
+   - 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

seboolean

@@ -43,7 +43,7 @@ options:
     default: null
     choices: [ "true", "false" ]
 examples:
-   - code: seboolean name=httpd_can_network_connect state=true persistent=yes
+   - code: "seboolean: name=httpd_can_network_connect state=true persistent=yes"
      description: Set I(httpd_can_network_connect) SELinux flag to I(true) and I(persistent)
 notes:
    - Not tested on any debian based system

selinux

@@ -43,9 +43,9 @@ options:
     required: false
     default: "/etc/selinux/config"
 examples:
-   - code: selinux policy=targeted state=enforcing
-   - code: selinux policy=targeted state=permissive
-   - code: selinux state=disabled
+   - 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 ]

service

@@ -53,15 +53,15 @@ options:
         description:
         - Whether the service should start on boot.
 examples:
-    - code: service name=httpd state=started
+    - code: "service: name=httpd state=started"
       description: Example action from Ansible Playbooks
-    - code: service name=httpd state=stopped
+    - code: "service: name=httpd state=stopped"
       description: Example action from Ansible Playbooks
-    - code: service name=httpd state=restarted
+    - code: "service: name=httpd state=restarted"
       description: Example action from Ansible Playbooks
-    - code: service name=httpd state=reloaded
+    - code: "service: name=httpd state=reloaded"
       description: Example action from Ansible Playbooks
-    - code: service name=foo pattern=/usr/bin/foo state=started
+    - code: "service: name=foo pattern=/usr/bin/foo state=started"
       description: Example action from Ansible Playbooks
 '''
 

shell

@@ -28,7 +28,7 @@ options:
     required: false
     default: null
 examples:
-   - code: shell somescript.sh >> somelog.txt
+   - code: "shell: somescript.sh >> somelog.txt"
      description: Execute the command in remote shell
 notes:
    -  If you want to execute a command securely and predicably, it may be

subversion

@@ -43,7 +43,7 @@ options:
     default: yes
     choices: [ "yes", "no" ]
 examples:
-   - code: subversion repo=svn+ssh://an.example.org/path/to/repo dest=/src/checkout
+   - code: "subversion: repo=svn+ssh://an.example.org/path/to/repo dest=/src/checkout"
      description: Export subversion repository in a specified folder
 notes:
    - Requires subversion and grep on the client.

supervisorctl

@@ -39,7 +39,7 @@ options:
     default: null
     choices: [ "started", "stopped", "restarted" ]
 examples:
-   - code: supervisorctl name=my_app state=started
+   - code: "supervisorctl: name=my_app state=started"
      description: Manage the state of program I(my_app) to be in I(started) state.
 requirements: [ ]
 author: Matt Wright

template

@@ -9,6 +9,12 @@ description:
        (U(http://jinja.pocoo.org/docs/)) - documentation on the template
        formatting can be found in the Template Designer Documentation
        (U(http://jinja.pocoo.org/docs/templates/)).
+     - "Four additional variables can be used in templates: C(ansible_managed) 
+       (configurable via the C(defaults) section of C(ansible.cfg)) contains a string
+       which can be used to describe the template name, host, modification time of the
+       template file and the owner uid, C(template_host) contains the node name of 
+       the template's machine, C(template_uid) the owner, and C(template_path) the
+       file name."
 options:
   src:
     description:
@@ -33,7 +39,7 @@ options:
       - 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
+   - code: "template: src=/mytemplates/foo.j2 dest=/etc/file.conf owner=bin group=wheel mode=0644"
      description: "Example from Ansible Playbooks"
 notes:
   - Since Ansible version 0.9, templates are loaded with C(trim_blocks=True).

user

@@ -137,11 +137,11 @@ options:
               passphrase is provided, the SSH key will default to
               having no passphrase.
 examples:
-    - code: user name=johnd comment="John Doe" uid=1040
+    - 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
+    - code: "user: name=johnd state=absent remove=yes"
       description: "Remove the user 'johnd'"
-    - code: user name=jsmith ssh_key=generate ssh_key_bits=2048
+    - code: 'user: name=jsmith ssh_key=generate ssh_key_bits=2048'
       description: "Create a 2048-bit SSH key for user jsmith"
 '''
 

virt

@@ -42,7 +42,7 @@ options:
       - in addition to state management, various non-idempotent commands are available. See examples
     required: false
 examples:
-   - code: virt guest=alpha state=running
+   - code: "virt: guest=alpha state=running"
      description: "Example from Ansible Playbooks"
    - code: ansible host -m virt -a "guest=alpha command=status"
      description: "Example guest management with C(/usr/bin/ansible)"

wait_for

@@ -61,7 +61,7 @@ options:
     choices: [ "started", "stopped" ]
     default: "started"
 examples:
-   - code: wait_for port=8000 delay=10
+   - code: "wait_for: port=8000 delay=10"
      description: "Example from Ansible Playbooks"
 notes: []
 requirements: null

yum

@@ -50,9 +50,9 @@ options:
     choices: [ "present", "latest", "absent" ]
     default: "present"
 examples:
-   - code: yum name=httpd state=latest
-   - code: yum name=httpd state=removed
-   - code: yum name=httpd state=installed
+   - code: "yum: name=httpd state=latest"
+   - code: "yum: name=httpd state=removed"
+   - code: "yum: name=httpd state=installed"
 notes: []
 # informational: requirements for nodes
 requirements: [ yum, rpm ]