Lots of docsite additions for new features + cleanup lineinfile YAML docs

docsite/rst/playbooks2.rst

@@ -946,6 +946,46 @@ feature produces a large amount of output, it is best used when checking a singl
 
     ansible-playbook foo.yml --check --diff --limit foo.example.com
 
+Passing Complex Arguments From Dictionaries
+```````````````````````````````````````````
+
+As a review, most tasks in ansbile are of this form::
+
+    tasks:
+
+      - name: ensure the cobbler package is installed
+        yum: name=cobbler state=installed
+        
+However, in some cases, it may be useful to feed arguments directly in from a hash (dictionary).  In fact, a very small
+number of modules (the CloudFormations module is one) actually require complex arguments that can't be fit
+into a key=value system.  To pass arguments in from a hash (dictionary), do this::
+
+    tasks:
+
+      - name: call a module that requires some complex arguments
+        module_name_goes_here: asdf=1234
+        args:
+           fibonacci_list
+             - 1
+             - 1
+             - 2
+             - 3
+           my_pets:
+             dogs:
+               - fido
+               - woof    
+             fish: 
+               - limpet
+               - nemo
+
+While complex arguments can be fed to most modules in Ansible, they should only be used where needed.  Note
+that variable interpolation works exactly as you would suspect, so you can use "${foo}" and so on in values
+inside of the dictionary you pass to "args".
+
+If both key=value arguments are given along with 'args', the key=value arguments take priority.  This technically
+means you can set defaults by using 'args' if you so choose, though that is not the intended purpose of this
+feature.
+
 Advanced Task Includes
 ``````````````````````
 

library/lineinfile

@@ -89,17 +89,22 @@ options:
          get the original file back if you somehow clobbered it incorrectly.
   others:
      description:
-       - All arguments accepted by the M(file) module also work here. If you 
+       - All arguments accepted by the M(file) module also work here. 
-       use file arguments with C(state=absent) and the file exists, it's perms, 
-       ownership or SE linux context will be updated if needed.
      required: false
-examples:
+"""
-   - code: 'lineinfile: dest=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled'
+
-   - code: 'lineinfile: dest=/etc/sudoers state=absent regexp="^%wheel"'
+EXAMPLES = """
-   - code: "lineinfile: dest=/etc/host regexp='^127\.0\.0\.1' line='127.0.0.1 localhost' owner=root group=root mode=0644"
+   lineinfile: dest=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled
-   - code: 'lineinfile: dest=/etc/httpd/conf/httpd.conf regexp="^Listen " insertafter="^#Listen " line="Listen 8080"'
+
-   - code: 'lineinfile: dest=/etc/services regexp="^# port for http" insertbefore="^www.*80/tcp" line="# port for http by default"'
+   lineinfile: dest=/etc/sudoers state=absent regexp="^%wheel"
-   - code: "lineinfile: \\\"dest=/etc/sudoers state=present regexp='^%wheel' line ='%wheel ALL=(ALL) NOPASSWD: ALL'\\\""
+
+   lineinfile: dest=/etc/host regexp='^127\.0\.0\.1' line='127.0.0.1 localhost' owner=root group=root mode=0644
+
+   lineinfile: dest=/etc/httpd/conf/httpd.conf regexp="^Listen " insertafter="^#Listen " line="Listen 8080"
+
+   lineinfile: dest=/etc/services regexp="^# port for http" insertbefore="^www.*80/tcp" line="# port for http by default"
+
+   lineinfile: \\\"dest=/etc/sudoers state=present regexp='^%wheel' line ='%wheel ALL=(ALL) NOPASSWD: ALL'\\\"
 """