Migrated all examples: in DOCUMENTATION=''' string to standalone EXAMPLES=''' string
  Added deprecation warning to moduledev.rst and remove deprecated example from it
  Fixed up a few typos and uppercased some acronyms.
  add consistency to how EXAMPLES are formatted

And also be liberal in what ansible-doc accepts as an empty
requirements specification.

While here fix a typo in template module documentation
wrt jinja2 overrides example.

Signed-off-by: Brian Coca <briancoca+dev@gmail.com>

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

This change includes:

 - (on possibly older python versions ?) a string variable test using the 'is' operator fails (so it always return ok immediately after initial delay)
 - add a missing socket.settimeout() for the state=started case (if the machine does not exist, timeout defaults to 60 seconds)
 - add a connect_timeout option to customize the default connection timeout
 - use socket.shutdown(2) to close immediately
 - return the elapsed time

This takes started, stopped and restarted.

Started returns when connecting is possible.
Stopped when connecting is not possible.
Restarted first waits for connecting to be impossible and returns when it is
possible again.

This module waits until a specific port on a given host can be connected to.

Add encoding lines to python modules such that they can take unicode options if they are fed them, since the
AnsibleModule stuff no longer base64 encodes for simplicity and speed reasons.

Port the file module over to the new common code infrastructure + cleanup some redundant imports since the module code already imports those things.

By defining a main function here, and including it ahead of the boilerplate insertion symbol, tracebacks are
now accurate with respect to the main function, but may include lines not in the original file.  A lot better
than before, where they were offset.

Added code to allow insertion of boilerplate into modules to make them able to share lots of code, the result
should be a huge reduction of total ansible source, at a slight cost of difficulty in original module development.

We need to apply this now to all modules, but may need to have some exemptions to things like command, which should
subclass this module.

The ohai and facter modules use /usr/bin/logger to log the fact that
they have been invoked.  I added 'import os' to the ping module
so that it could have the same syslog statements as the other modules.
I separated the condensed:
    shlex.split(open(argfile, 'r').read())
into two separate statements similar to the other modules.

Check md5sum before overwriting a file. Unconditionally copying changes the timestamp.

still needs to daemonize.  Then, once done, playbook can be taught how to poll async within the
timing window.

all modules take a common parameter name.  But more or less we still work idempotently
in modules.

module works differently now

starter manpage for modules

allow template file location to be passed into template & setup modules

also fix a bug/typo in the reporting from playbook

onchange events like Puppet's file providers do.