Merge pull request #5604 from samdoran/examples-syntax-fix-batch1

Examples syntax change batch1

10 files changed, 213 insertions, 103 deletions

diff --git a/commands/script.py b/commands/script.py
index 1d07bbad..be8d9a1b 100644
--- a/commands/script.py
+++ b/commands/script.py
@@ -47,7 +47,7 @@ options:
 notes:
   - It is usually preferable to write Ansible modules than pushing scripts. Convert your script to an Ansible module for bonus points!
   - The ssh connection plugin will force psuedo-tty allocation via -tt when scripts are executed. psuedo-ttys do not have a stderr channel and all stderr is sent to stdout. If you depend on separated stdout and stderr result keys, please switch to a copy+command set of tasks instead of using script.
-author: 
+author:
     - Ansible Core Team
     - Michael DeHaan
 """
@@ -57,8 +57,12 @@ EXAMPLES = '''
 - script: /some/local/script.sh --some-arguments 1234
 
 # Run a script that creates a file, but only if the file is not yet created
-- script: /some/local/create_file.sh --some-arguments 1234 creates=/the/created/file.txt
+- script: /some/local/create_file.sh --some-arguments 1234
+  args:
+    creates: /the/created/file.txt
 
 # Run a script that removes a file, but only if the file is not yet removed
-- script: /some/local/remove_file.sh --some-arguments 1234 removes=/the/removed/file.txt
+- script: /some/local/remove_file.sh --some-arguments 1234
+  args:
+    removes: /the/removed/file.txt
 '''
diff --git a/commands/shell.py b/commands/shell.py
index 96bbae5e..ca17ddda 100644
--- a/commands/shell.py
+++ b/commands/shell.py
@@ -68,11 +68,11 @@ notes:
       playbooks will follow the trend of using M(command) unless M(shell) is
       explicitly required. When running ad-hoc commands, use your best
       judgement.
-   -  To sanitize any variables passed to the shell module, you should use 
+   -  To sanitize any variables passed to the shell module, you should use
       "{{ var | quote }}" instead of just "{{ var }}" to make sure they don't include evil things like semicolons.
 
 requirements: [ ]
-author: 
+author:
     - Ansible Core Team
     - Michael DeHaan
 '''
@@ -83,7 +83,9 @@ EXAMPLES = '''
 - shell: somescript.sh >> somelog.txt
 
 # Change the working directory to somedir/ before executing the command.
-- shell: somescript.sh >> somelog.txt chdir=somedir/
+- shell: somescript.sh >> somelog.txt
+  args:
+    chdir: somedir/
 
 # You can also use the 'args' form to provide the options. This command
 # will change the working directory to somedir/ and will only run when
@@ -146,4 +148,4 @@ stdout_lines:
     returned: always
     type: list of strings
     sample: [u'Clustering node rabbit@slave1 with rabbit@master ...']
-'''
\ No newline at end of file
+'''
diff --git a/database/mysql/mysql_db.py b/database/mysql/mysql_db.py
index f98547b9..2b6a19d5 100644
--- a/database/mysql/mysql_db.py
+++ b/database/mysql/mysql_db.py
@@ -79,11 +79,18 @@ extends_documentation_fragment: mysql
 
 EXAMPLES = '''
 # Create a new database with name 'bobdata'
-- mysql_db: name=bobdata state=present
+- mysql_db:
+    name: bobdata
+    state: present
 
 # Copy database dump file to remote host and restore it to database 'my_db'
-- copy: src=dump.sql.bz2 dest=/tmp
-- mysql_db: name=my_db state=import target=/tmp/dump.sql.bz2
+- copy:
+    src: dump.sql.bz2
+    dest: /tmp
+- mysql_db:
+    name: my_db
+    state: import
+    target: /tmp/dump.sql.bz2
 
 # Dumps all databases to hostname.sql
 - mysql_db: state=dump name=all target=/tmp/{{ inventory_hostname }}.sql
diff --git a/database/mysql/mysql_user.py b/database/mysql/mysql_user.py
index 010cdce6..87e8318a 100644
--- a/database/mysql/mysql_user.py
+++ b/database/mysql/mysql_user.py
@@ -111,43 +111,89 @@ extends_documentation_fragment: mysql
 
 EXAMPLES = """
 # Removes anonymous user account for localhost
-- mysql_user: name='' host=localhost state=absent
+- mysql_user:
+    name: ''
+    host: localhost
+    state: absent
 
 # Removes all anonymous user accounts
-- mysql_user: name='' host_all=yes state=absent
+- mysql_user:
+    name: ''
+    host_all: yes
+    state: absent
 
 # Create database user with name 'bob' and password '12345' with all database privileges
-- mysql_user: name=bob password=12345 priv=*.*:ALL state=present
+- mysql_user:
+    name: bob
+    password: 12345
+    priv: '*.*:ALL'
+    state: present
 
 # Create database user with name 'bob' and previously hashed mysql native password '*EE0D72C1085C46C5278932678FBE2C6A782821B4' with all database privileges
-- mysql_user: name=bob password='*EE0D72C1085C46C5278932678FBE2C6A782821B4' encrypted=yes priv=*.*:ALL state=present
+- mysql_user:
+    name: bob
+    password: '*EE0D72C1085C46C5278932678FBE2C6A782821B4'
+    encrypted: yes
+    priv: '*.*:ALL'
+    state: present
 
 # Creates database user 'bob' and password '12345' with all database privileges and 'WITH GRANT OPTION'
-- mysql_user: name=bob password=12345 priv=*.*:ALL,GRANT state=present
+- mysql_user:
+    name: bob
+    password: 12345
+    priv: '*.*:ALL,GRANT'
+    state: present
 
 # Modify user Bob to require SSL connections. Note that REQUIRESSL is a special privilege that should only apply to *.* by itself.
-- mysql_user: name=bob append_privs=true priv=*.*:REQUIRESSL state=present
+- mysql_user:
+    name: bob
+    append_privs: true
+    priv: '*.*:REQUIRESSL'
+    state: present
 
 # Ensure no user named 'sally'@'localhost' exists, also passing in the auth credentials.
-- mysql_user: login_user=root login_password=123456 name=sally state=absent
+- mysql_user:
+    login_user: root
+    login_password: 123456
+    name: sally
+    state: absent
 
 # Ensure no user named 'sally' exists at all
-- mysql_user: name=sally host_all=yes state=absent
+- mysql_user:
+    name: sally
+    host_all: yes
+    state: absent
 
 # Specify grants composed of more than one word
-- mysql_user: name=replication password=12345 priv="*.*:REPLICATION CLIENT" state=present
+- mysql_user:
+    name: replication
+    password: 12345
+    priv: "*.*:REPLICATION CLIENT"
+    state: present
 
 # Revoke all privileges for user 'bob' and password '12345'
-- mysql_user: name=bob password=12345 priv=*.*:USAGE state=present
+- mysql_user:
+    name: bob
+    password: 12345
+    priv: "*.*:USAGE"
+    state: present
 
 # 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
+- mysql_user:
+    name: root
+    password: abc123
+    login_unix_socket: /var/run/mysqld/mysqld.sock
 
 # Example of skipping binary logging while adding user 'bob'
-- mysql_user: name=bob password=12345 priv=*.*:USAGE state=present sql_log_bin=no
+- mysql_user:
+    name: bob
+    password: 12345
+    priv: "*.*:USAGE"
+    state: present
+    sql_log_bin: no
 
 # Example .my.cnf file for setting the root password
 
diff --git a/database/mysql/mysql_variables.py b/database/mysql/mysql_variables.py
index 5cb6bf6f..014b768d 100644
--- a/database/mysql/mysql_variables.py
+++ b/database/mysql/mysql_variables.py
@@ -44,10 +44,13 @@ extends_documentation_fragment: mysql
 '''
 EXAMPLES = '''
 # Check for sync_binlog setting
-- mysql_variables: variable=sync_binlog
+- mysql_variables:
+    variable: sync_binlog
 
 # Set read_only variable to 1
-- mysql_variables: variable=read_only value=1
+- mysql_variables:
+    variable: read_only
+    value: 1
 '''
 
 
diff --git a/database/postgresql/postgresql_db.py b/database/postgresql/postgresql_db.py
index 64871ed1..70cc96dc 100755
--- a/database/postgresql/postgresql_db.py
+++ b/database/postgresql/postgresql_db.py
@@ -95,16 +95,18 @@ author: "Ansible Core Team"
 
 EXAMPLES = '''
 # Create a new database with name "acme"
-- postgresql_db: name=acme
+- postgresql_db:
+    name: 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: name=acme
-                 encoding='UTF-8'
-                 lc_collate='de_DE.UTF-8'
-                 lc_ctype='de_DE.UTF-8'
-                 template='template0'
+- postgresql_db:
+    name: acme
+    encoding: UTF-8
+    lc_collate: de_DE.UTF-8
+    lc_ctype: de_DE.UTF-8
+    template: template0
 '''
 
 try:
diff --git a/database/postgresql/postgresql_privs.py b/database/postgresql/postgresql_privs.py
index 74b2630b..ea49a55f 100644
--- a/database/postgresql/postgresql_privs.py
+++ b/database/postgresql/postgresql_privs.py
@@ -143,90 +143,90 @@ EXAMPLES = """
 # On database "library":
 # GRANT SELECT, INSERT, UPDATE ON TABLE public.books, public.authors
 # TO librarian, reader WITH GRANT OPTION
-- postgresql_privs: >
-    database=library
-    state=present
-    privs=SELECT,INSERT,UPDATE
-    type=table
-    objs=books,authors
-    schema=public
-    roles=librarian,reader
-    grant_option=yes
+- postgresql_privs:
+    database: library
+    state: present
+    privs: SELECT,INSERT,UPDATE
+    type: table
+    objs: books,authors
+    schema: public
+    roles: librarian,reader
+    grant_option: yes
 
 # Same as above leveraging default values:
-- postgresql_privs: >
-    db=library
-    privs=SELECT,INSERT,UPDATE
-    objs=books,authors
-    roles=librarian,reader
-    grant_option=yes
+- postgresql_privs:
+    db: library
+    privs: SELECT,INSERT,UPDATE
+    objs: books,authors
+    roles: librarian,reader
+    grant_option: yes
 
 # 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: >
-    db=library
-    state=present
-    priv=INSERT
-    obj=books
-    role=reader
-    grant_option=no
+# isn't already the case (since state: present).
+- postgresql_privs:
+    db: library
+    state: present
+    priv: INSERT
+    obj: books
+    role: reader
+    grant_option: no
 
 # 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: >
-    db=library
-    state=absent
-    privs=INSERT,UPDATE
-    objs=ALL_IN_SCHEMA
-    role=reader
+- postgresql_privs:
+    db: library
+    state: absent
+    privs: INSERT,UPDATE
+    objs: ALL_IN_SCHEMA
+    role: reader
 
 # GRANT ALL PRIVILEGES ON SCHEMA public, math TO librarian
-- postgresql_privs: >
-    db=library
-    privs=ALL
-    type=schema
-    objs=public,math
-    role=librarian
+- postgresql_privs:
+    db: library
+    privs: ALL
+    type: schema
+    objs: public,math
+    role: librarian
 
 # GRANT ALL PRIVILEGES ON FUNCTION math.add(int, int) TO librarian, reader
 # Note the separation of arguments with colons.
-- postgresql_privs: >
-    db=library
-    privs=ALL
-    type=function
-    obj=add(int:int)
-    schema=math
-    roles=librarian,reader
+- postgresql_privs:
+    db: library
+    privs: ALL
+    type: function
+    obj: add(int:int)
+    schema: math
+    roles: librarian,reader
 
 # 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: >
-    db=library
-    type=group
-    objs=librarian,reader
-    roles=alice,bob
-    admin_option=yes
+- postgresql_privs:
+    db: library
+    type: group
+    objs: librarian,reader
+    roles: alice,bob
+    admin_option: yes
 
 # GRANT ALL PRIVILEGES ON DATABASE library TO librarian
-# Note that here "db=postgres" specifies the database to connect to, not the
+# 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: >
-    db=postgres
-    privs=ALL
-    type=database
-    obj=library
-    role=librarian
+- postgresql_privs:
+    db: postgres
+    privs: ALL
+    type: database
+    obj: library
+    role: librarian
 
 # 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: >
-    db=library
-    privs=ALL
-    type=database
-    role=librarian
+- postgresql_privs:
+    db: library
+    privs: ALL
+    type: database
+    role: librarian
 """
 
 try:
diff --git a/database/postgresql/postgresql_user.py b/database/postgresql/postgresql_user.py
index d8b0b8bb..532e8645 100644
--- a/database/postgresql/postgresql_user.py
+++ b/database/postgresql/postgresql_user.py
@@ -142,22 +142,41 @@ author: "Ansible Core Team"
 
 EXAMPLES = '''
 # Create django user and grant access to database and products table
-- postgresql_user: db=acme name=django password=ceec4eif7ya priv=CONNECT/products:ALL
+- postgresql_user:
+    db: acme
+    name: 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: name=rails password=secret role_attr_flags=CREATEDB,NOSUPERUSER
+- postgresql_user:
+    name: rails
+    password: secret
+    role_attr_flags: CREATEDB,NOSUPERUSER
 
 # Remove test user privileges from acme
-- postgresql_user: db=acme name=test priv=ALL/products:ALL state=absent fail_on_user=no
+- postgresql_user:
+    db: acme
+    name: test
+    priv: "ALL/products:ALL"
+    state: absent
+    fail_on_user: no
 
 # Remove test user from test database and the cluster
-- postgresql_user: db=test name=test priv=ALL state=absent
+- postgresql_user:
+    db: test
+    name: test
+    priv: ALL
+    state: absent
 
 # Example privileges string format
 INSERT,UPDATE/table:SELECT/anothertable:ALL
 
 # Remove an existing user's password
-- postgresql_user: db=test user=test password=NULL
+- postgresql_user:
+    db: test
+    user: test
+    password: NULL
 '''
 
 import re
diff --git a/files/acl.py b/files/acl.py
index 2b898452..4974b6bb 100644
--- a/files/acl.py
+++ b/files/acl.py
@@ -97,19 +97,38 @@ notes:
 
 EXAMPLES = '''
 # Grant user Joe read access to a file
-- acl: name=/etc/foo.conf entity=joe etype=user permissions="r" state=present
+- acl:
+    name: /etc/foo.conf
+    entity: joe
+    etype: user
+    permissions: r
+    state: present
 
 # Removes the acl for Joe on a specific file
-- acl: name=/etc/foo.conf entity=joe etype=user state=absent
+- acl:
+    name: /etc/foo.conf
+    entity: joe
+    etype: user
+    state: absent
 
 # Sets default acl for joe on foo.d
-- acl: name=/etc/foo.d entity=joe etype=user permissions=rw default=yes state=present
+- acl:
+    name: /etc/foo.d
+    entity: joe
+    etype: user
+    permissions: rw
+    default: yes
+    state: present
 
 # Same as previous but using entry shorthand
-- acl: name=/etc/foo.d entry="default:user:joe:rw-" state=present
+- acl:
+    name: /etc/foo.d
+    entry: "default:user:joe:rw-"
+    state: present
 
 # Obtain the acl for a specific file
-- acl: name=/etc/foo.conf
+- acl:
+    name: /etc/foo.conf
   register: acl_info
 '''
 
diff --git a/files/assemble.py b/files/assemble.py
index 39edbdd3..d1d1bb34 100644
--- a/files/assemble.py
+++ b/files/assemble.py
@@ -95,13 +95,21 @@ extends_documentation_fragment:
 
 EXAMPLES = '''
 # Example from Ansible Playbooks
-- assemble: src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf
+- assemble:
+    src: /etc/someapp/fragments
+    dest: /etc/someapp/someapp.conf
 
 # When a delimiter is specified, it will be inserted in between each fragment
-- assemble: src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf delimiter='### START FRAGMENT ###'
+- assemble:
+    src: /etc/someapp/fragments
+    dest: /etc/someapp/someapp.conf
+    delimiter: '### START FRAGMENT ###'
 
 # Copy a new "sshd_config" file into place, after passing validation with sshd
-- assemble: src=/etc/ssh/conf.d/ dest=/etc/ssh/sshd_config validate='/usr/sbin/sshd -t -f %s'
+- assemble:
+    src: /etc/ssh/conf.d/
+    dest: /etc/ssh/sshd_config
+    validate: '/usr/sbin/sshd -t -f %s'
 '''
 
 import codecs