Only allocate a PTY when sudo is used

Postpone the paramiko.Channel.get_pty until we know sudo is used. If
sudo is not used, then we do not need a PTY. In fact, the paramiko docs
explicitly state that it's not desirable to allocate a PTY for a simple
exec_command.

Signed-off-by: martin f. krafft <madduck@madduck.net>
Initialise PTY from calling environment

If we need to acquire a PTY for sudo's use, then it should really
inherit the capabilities of the calling environment. This is what
OpenSSH does, and so it makes sense to copy this behaviour for the
paramiko connection type.

Closes: #2065
Signed-off-by: martin f. krafft <madduck@madduck.net>
Add support for additional EXAMPLES string in Ansible modules
return DOC and EXAMPLES as a list
add moduledev explanation
more
Removes exception is sysctl file is missing

When syscl file was missing, sysctl module was complaining about it and
bailing out.
This behaviour prevents usage of /etc/sysctl.d directory, present in
some distributions.
This patch accepts a missing sysctl.conf file so sysctl.d directory can
be used.
However, it will bail out if the destination directory doesn't exist.
Changed when new sysctl file is created

When destination sysctl file is missing, it is created.
But, for idempotency purposes, the creation process now takes place just before it is used, in the
main code path so an empty file is not left over if the code
module.fail_jsons before the file is really used.
Removes useless empty string write

It s not necessary to write an empty string for the file to be created.
Add virtualenv_site_packages param to easy_install
Easy_install and pip module support a virtualenv_command parameter.

This allows flexible selection of the Python version to use while
creating the virtualenv.
Add postgresql_db and postgresql_use checkmode.
Add force= and make thirsty= an alias for backward compatibility
Adds filter option to setup module

Adds facts filtering using fnmatch, via the 'filter' option.

Usage:
ansible -m setup -a 'filter=ansible_*_mb'
Adds example for filter option in setup module

Added an example on how to filter keys returned by the module.
Added more examples for the filter option in setup

Added examples covering all available globs
Added a use case of filtering only facts returned by facter
Fixes unused var and avoid reassigning keys

Changed code so key doesn't get reassigned in loop
Made use of filtr variable
Prevent traceback when /etc/mtab is not available

* get_file_contents returns None when file is not available.
  When /etc/mtab is pointing to /proc/mounts and /proc is not
  mounted, mtab.split will traceback.
Check presence of files under /proc before opening them
Fix diff output vertical spacing
Add support for running modules chrooted in a local dir

Adds 'chroot' connection for executing modules chrooted to
a local dir. Requires running ansible as root.

chroot dirs should be specified in the inventory like any
other host.

You can do things like:

$ sudo -E ansible -vvv -f 1 "./chroot1,./chroot2" -c chroot \
  all -m setup
$ sudo -E ansible-playbook -vvv -f 1 -i "./chroot1,./chroot2" \
  -c chroot some-playbook.yml

some-playbook.yml:
---
- hosts: all
  tasks:
    - name: echo something
      shell: echo "Yaaay!" >/tmp/foobar.txt
    - name: install less
      apt: pkg=less state=latest
Moved key filtering

Key filtering moved before returning results
Fixed file-path in comment from examples.yml to intro_example.yml.