fixes to config/setting retrieval

- better variable precedence management
- universal plugin option handling
- also updated comments for future directions
- leverage fragments for plugins
- removed fact namespacing
- added 'firendly name' field
- updated missing descriptions
- removed some unused yaml entries, updated others to reflect possible future
- documented more plugins
- allow reading docs using alias
- short licenses
- corrected args for 'all plugins'
- fixed -a option for ansible-doc
- updated vars plugins to allow docs
- fixed 'gathering'
- only set options IF connection
- added path list and renamed pathspec mostly the diff is , vs : as separator
- readded removed config entries that were deprecated but had no message ... and deprecated again
- now deprecated entries give warning when set

1 files changed, 108 insertions, 126 deletions

diff --git a/lib/ansible/plugins/connection/ssh.py b/lib/ansible/plugins/connection/ssh.py
index bbdef533da..6b3d1ab3fa 100644
--- a/lib/ansible/plugins/connection/ssh.py
+++ b/lib/ansible/plugins/connection/ssh.py
@@ -1,22 +1,9 @@
-# (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
+# Copyright (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
 # Copyright 2015 Abhijit Menon-Sen <ams@2ndQuadrant.com>
 # Copyright 2017 Toshio Kuratomi <tkuratomi@ansible.com>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-#
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
 '''
 DOCUMENTATION:
     connection: ssh
@@ -26,114 +13,111 @@ DOCUMENTATION:
     author: ansible (@core)
     version_added: historical
     options:
-        host:
-            description: Hostname/ip to connect to.
-            default: inventory_hostname
-            vars:
-                 - name: ansible_host
-                 - name: ansible_ssh_host
-        host_key_checking:
-            constants:
-                - name: HOST_KEY_CHECKING
-            description: Determines if ssh should check host keys
-            type: boolean
-            ini:
-                - section: defaults
-                  key: 'host_key_checking'
-            env:
-                - name: ANSIBLE_HOST_KEY_CHECKING
-        password:
-            description: Authentication password for the C(remote_user). Can be supplied as CLI option.
-            vars:
-                - name: ansible_password
-                - name: ansible_ssh_pass
-        ssh_args:
-            description: Arguments to pass to all ssh cli tools
-            default: '-C -o ControlMaster=auto -o ControlPersist=60s'
-            ini:
-                - section: 'ssh_connection'
-                  key: 'ssh_args'
-            env:
-                - name: ANSIBLE_SSH_ARGS
-        ssh_common_args:
-            description: Common extra args for all ssh CLI tools
-            vars:
-                - name: ansible_ssh_common_args
-        ssh_executable:
-            default: ssh
-            description:
-              - This defines the location of the ssh binary. It defaults to `ssh` which will use the first ssh binary available in $PATH.
-              - This option is usually not required, it might be useful when access to system ssh is restricted,
-                or when using ssh wrappers to connect to remote hosts.
-            env: [{name: ANSIBLE_SSH_EXECUTABLE}]
-            ini:
-            - {key: ssh_executable, section: ssh_connection}
-            yaml: {key: ssh_connection.ssh_executable}
-            const:
-                - name: ANSIBLE_SSH_EXECUTABLE
-            version_added: "2.2"
-        scp_extra_args:
-            description: Extra exclusive to the 'scp' CLI
-            vars:
-                - name: ansible_scp_extra_args
-        sftp_extra_args:
-            description: Extra exclusive to the 'sftp' CLI
-            vars:
-                - name: ansible_sftp_extra_args
-        ssh_extra_args:
-            description: Extra exclusive to the 'ssh' CLI
-            vars:
-                - name: ansible_ssh_extra_args
-        ssh_retries:
-            # constant: ANSIBLE_SSH_RETRIES
-            description: Number of attempts to connect.
-            default: 3
-            env:
-              - name: ANSIBLE_SSH_RETRIES
-            ini:
-              - section: connection
-                key: retries
-              - section: ssh_connection
-                key: retries
-        port:
-            description: Remote port to connect to.
-            type: int
-            default: 22
-            ini:
-              - section: defaults
-                key: remote_port
-            env:
-              - name: ANSIBLE_REMOTE_PORT
-            vars:
-              - name: ansible_port
-              - name: ansible_ssh_port
-        remote_user:
-            description:
-                - User name with which to login to the remote server, normally set by the remote_user keyword.
-                - If no user is supplied, Ansible will let the ssh client binary choose the user as it normally
-            ini:
+      host:
+          description: Hostname/ip to connect to.
+          default: inventory_hostname
+          vars:
+               - name: ansible_host
+               - name: ansible_ssh_host
+      host_key_checking:
+          #constant: HOST_KEY_CHECKING
+          description: Determines if ssh should check host keys
+          type: boolean
+          ini:
               - section: defaults
-                key: remote_user
-            env:
-              - name: ANSIBLE_REMOTE_USER
-            vars:
-              - name: ansible_user
-              - name: ansible_ssh_user
-        pipelining:
-            default: ANSIBLE_PIPELINING
-            description:
-              - Pipelining reduces the number of SSH operations required to execute a module on the remote server,
-                by executing many Ansible modules without actual file transfer.
-              - This can result in a very significant performance improvement when enabled.
-              - However this conflicts with privilege escalation (become).
-                For example, when using sudo operations you must first disable 'requiretty' in the sudoers file for the target hosts,
-                which is why this feature is disabled by default.
-            env: [{name: ANSIBLE_SSH_PIPELINING}]
-            ini:
-            - {key: pipelining, section: ssh_connection}
-            type: boolean
-            vars: [{name: ansible_ssh_pipelining}]
-
+                key: 'host_key_checking'
+          env:
+              - name: ANSIBLE_HOST_KEY_CHECKING
+      password:
+          description: Authentication password for the C(remote_user). Can be supplied as CLI option.
+          vars:
+              - name: ansible_password
+              - name: ansible_ssh_pass
+      ssh_args:
+          description: Arguments to pass to all ssh cli tools
+          default: '-C -o ControlMaster=auto -o ControlPersist=60s'
+          ini:
+              - section: 'ssh_connection'
+                key: 'ssh_args'
+          env:
+              - name: ANSIBLE_SSH_ARGS
+      ssh_common_args:
+          description: Common extra args for all ssh CLI tools
+          vars:
+              - name: ansible_ssh_common_args
+      ssh_executable:
+          default: ssh
+          description:
+            - This defines the location of the ssh binary. It defaults to `ssh` which will use the first ssh binary available in $PATH.
+            - This option is usually not required, it might be useful when access to system ssh is restricted,
+              or when using ssh wrappers to connect to remote hosts.
+          env: [{name: ANSIBLE_SSH_EXECUTABLE}]
+          ini:
+          - {key: ssh_executable, section: ssh_connection}
+          yaml: {key: ssh_connection.ssh_executable}
+          #const: ANSIBLE_SSH_EXECUTABLE
+          version_added: "2.2"
+      scp_extra_args:
+          description: Extra exclusive to the 'scp' CLI
+          vars:
+              - name: ansible_scp_extra_args
+      sftp_extra_args:
+          description: Extra exclusive to the 'sftp' CLI
+          vars:
+              - name: ansible_sftp_extra_args
+      ssh_extra_args:
+          description: Extra exclusive to the 'ssh' CLI
+          vars:
+              - name: ansible_ssh_extra_args
+      ssh_retries:
+          # constant: ANSIBLE_SSH_RETRIES
+          description: Number of attempts to connect.
+          default: 3
+          env:
+            - name: ANSIBLE_SSH_RETRIES
+          ini:
+            - section: connection
+              key: retries
+            - section: ssh_connection
+              key: retries
+      port:
+          description: Remote port to connect to.
+          type: int
+          default: 22
+          ini:
+            - section: defaults
+              key: remote_port
+          env:
+            - name: ANSIBLE_REMOTE_PORT
+          vars:
+            - name: ansible_port
+            - name: ansible_ssh_port
+      remote_user:
+          description:
+              - User name with which to login to the remote server, normally set by the remote_user keyword.
+              - If no user is supplied, Ansible will let the ssh client binary choose the user as it normally
+          ini:
+            - section: defaults
+              key: remote_user
+          env:
+            - name: ANSIBLE_REMOTE_USER
+          vars:
+            - name: ansible_user
+            - name: ansible_ssh_user
+      pipelining:
+          default: ANSIBLE_PIPELINING
+          description:
+            - Pipelining reduces the number of SSH operations required to execute a module on the remote server,
+              by executing many Ansible modules without actual file transfer.
+            - This can result in a very significant performance improvement when enabled.
+            - However this conflicts with privilege escalation (become).
+              For example, when using sudo operations you must first disable 'requiretty' in the sudoers file for the target hosts,
+              which is why this feature is disabled by default.
+          env: [{name: ANSIBLE_SSH_PIPELINING}]
+          ini:
+          - {key: pipelining, section: ssh_connection}
+          type: boolean
+          vars: [{name: ansible_ssh_pipelining}]
 # TODO:
 # ANSIBLE_SSH_RETRIES
 
@@ -152,7 +136,6 @@ import fcntl
 import hashlib
 import os
 import pty
-import socket
 import subprocess
 import time
 
@@ -850,7 +833,6 @@ class Connection(ConnectionBase):
             else:
                 methods = ['sftp']
 
-        success = False
         for method in methods:
             returncode = stdout = stderr = None
             if method == 'sftp':