Document the user module

rst/modules.rst

@@ -47,10 +47,6 @@ If you want to run a command through the shell (say you are using
 '<', '>', '|', etc), you actually want the 'shell' module instead.  
 The 'command' module is much more secure as it's not affected by the user's environment.
 
-Example usage::
-
-    /sbin/shutdown -t now
-
 The given command will be executed on all selected nodes.  It will not
 be processed through the shell, so variables like "$HOME" and 
 operations like "<", ">", "|", and "&" will not work.  As such, all
@@ -60,6 +56,10 @@ This module does not support change hooks and returns the return code
 from the program as well as timing information about how long the
 command was running for.
 
+Example action from a :doc:`playbook`::
+
+    command /sbin/shutdown -t now
+
 
 .. _copy:
 
@@ -80,9 +80,12 @@ module.
 
 * Remote absolute path where the file should end up.
 
-
 This module also returns md5sum information about the resultant file.
 
+Example action from a :doc:`playbook`::
+
+    copy src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644
+
 
 .. _facter:
 
@@ -125,6 +128,12 @@ to the file module are also available when running the `copy` or `template` modu
 
 * name of group that should own the file or directory, as would be given to `chgrp`
 
+Example action from a :doc:`playbook`::
+
+    file dest=/etc/foo.conf owner=foo group=foo mode=0644
+    file dest=/some/path owner=foo group=foo state=directory
+    file dest/path/to/delete state=absent
+
 
 git
 ```
@@ -144,6 +153,10 @@ Deploys software (or files) from git checkouts.
 * What version to check out -- either the git SHA, the literal string
   ``HEAD``, or a tag name.
 
+Example action from a :doc:`playbook`::
+
+    git repo=git://foosball.example.org/path/to/repo.git dest=/srv/checkout version=release-0.22
+
 
 ohai
 ````
@@ -181,11 +194,16 @@ Controls services on remote machines.
   Started/stopped are idempotent actions that will not run commands
   unless necessary.  ``restarted`` will always bounce the service.
 
-
 *name*:
 
 * The name of the service.
 
+Example action from a :doc:`playbook`::
+
+    service name=httpd state=started
+    service name=httpd state=stopped
+    service name=httpd state=restarted
+
 
 .. _setup:
 
@@ -208,6 +226,16 @@ tell their source.  All variables are then bubbled up to the caller.
  * Any other parameters can be named basically anything, and set a
    ``key=value`` pair in the JSON file for use in templating.
 
+Example action from a :doc:`playbook`::
+
+    vars:
+        ntpserver: 'ntp.example.com'
+        xyz: 1234
+
+Example action from `/usr/bin/ansible`::
+
+    ansible -m all setup -a "ntpserver=ntp.example.com xyz=1234"
+
 
 .. _shell:
 
@@ -218,10 +246,6 @@ The shell module takes the command name followed by a list of
 arguments, space delimited.  It is almost exactly like the command module
 but runs the command through the shell rather than directly.
 
-Example usage::
-
-    find . | grep *.txt
-
 The given command will be executed on all selected nodes.  
 
 If you want to execute a command securely and predicably, it may
@@ -234,6 +258,10 @@ This module does not support change hooks and returns the return code
 from the program as well as timing information about how long the
 command was running for.
 
+Example action from a playbook::
+
+    shell somescript.sh >> somelog.txt
+
 
 .. _template:
 
@@ -254,9 +282,54 @@ module.
 
 * Location to render the template on the remote server.
 
-
 This module also returns md5sum information about the resultant file.
 
+Example action from a playbook::
+
+    template src=/srv/mytemplates/foo.j2 dest=/etc/foo.conf owner=foo group=foo mode=0644
+
+
+.. _user:
+
+user
+````
+
+Creates user accounts, manipulates existing user accounts, and removes user accounts.
+
+*name*:
+
+* Name of the user to create, remove, or edit
+
+*comment*:
+
+* Optionally sets the description of the user
+
+*gid*:
+
+* Optionally sets the primary group GID.  The user module will also be able to manipulate this.
+
+*shell*:
+
+* Optionally sets the user's shell.
+
+*createhome*:
+
+* Whether to create the user's home directory.  Takes 'yes', or 'no'.  The default is 'yes'.
+    
+*password*:
+
+* Sets the user's password to this crypted value.  Pass in a result from crypt.  See the users
+  example in the github examples directory for what this looks like in a playbook.
+
+*state*:
+
+* Defaults to 'present'.  When 'absent', the user account will be removed if present.
+
+Example action from a :doc:`playbook`::
+
+    user name=mdehaan comment=awesome passwd=awWxVV.JvmdHw createhome=yes
+    user name=mdehaan state=absent
+
 .. _yum:
 
 yum
@@ -278,6 +351,13 @@ Will install, upgrade, remove, and list packages with the yum package manager.
   various configuration attributes.  Values include 'installed', 'updates',
   'available', 'repos', or any package specifier.
 
+Example action from a :doc:`playbook`::
+
+    yum pkg=httpd ensure=latest
+    yum pkg=httpd ensure=removed
+    yum pkg=httpd ensure=installed
+
+
 Writing your own modules
 ````````````````````````