Enable documentation in plugins

Made ansible-doc more plugin agnostic
We can have docs in lookup, callback, connectionm strategy, etc
Use first docstring and make pepizis happy
generalized module_docs to plugin_docs
documented cartesian, ssh, default, jsonfile, etc as examples
changed lack of docs to warning when listing
made smarter about bad docstrings
better blacklisting
added handling of options/config/envs/etc
move blacklist to find_plugins, only need once

lib/ansible/plugins/cache/jsonfile.py

@@ -14,7 +14,15 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-
+'''
+DOCUMENTATION:
+    cache: jsonfile
+    short_description: File backed, JSON formated.
+    description:
+        - File backed cache that uses JSON as a format, the files are per host.
+    version_added: "1.9"
+    author: Brian Coca (@bcoca)
+'''
 # Make coding more python3-ish
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

lib/ansible/plugins/cache/memory.py

@@ -14,6 +14,17 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+'''
+DOCUMENTATION:
+    cache: memory
+    short_description: RAM backed, non persistent
+    description:
+        - RAM backed cache that is not persistent.
+    version_added: historical
+    author: core team (@ansible-core)
+'''
+
+
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 

lib/ansible/plugins/cache/pickle.py

@@ -14,6 +14,15 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+'''
+DOCUMENTATION:
+    cache: yaml
+    short_description: File backed, using Python's pickle.
+    description:
+        - File backed cache that uses Python's pickle serialization as a format, the files are per host.
+    version_added: "2.3"
+    author: Brian Coca (@bcoca)
+'''
 
 # Make coding more python3-ish
 from __future__ import (absolute_import, division, print_function)

lib/ansible/plugins/cache/yaml.py

@@ -14,6 +14,15 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+'''
+DOCUMENTATION:
+    cache: yaml
+    short_description: File backed, YAML formated.
+    description:
+        - File backed cache that uses YAML as a format, the files are per host.
+    version_added: "2.3"
+    author: Brian Coca (@bcoca)
+'''
 
 # Make coding more python3-ish
 from __future__ import (absolute_import, division, print_function)

lib/ansible/plugins/callback/default.py

@@ -14,7 +14,14 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-
+'''
+DOCUMENTATION:
+    callback: default
+    short_description: default Ansbile screen output
+    version_added: historical
+    description:
+        - This is the default output callback for ansible-playbook.
+'''
 # Make coding more python3-ish
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

lib/ansible/plugins/connection/local.py

@@ -15,6 +15,18 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+'''
+DOCUMENTATION:
+    connection: local
+    short_description: execute on controller
+    description:
+        - This connection plugin allows ansible to execute tasks on the Ansible 'controller' instead of on a remote host.
+    author: ansible (@core)
+    version_added: historical
+    notes:
+        - The remote user is ignored, the user with which the ansible CLI was executed is used instead.
+'''
+
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 

lib/ansible/plugins/connection/ssh.py

@@ -17,6 +17,84 @@
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 #
+'''
+DOCUMENTATION:
+    connection: ssh
+    short_description: connect via ssh client binary
+    description:
+        - This connection plugin allows ansible to communicate to the target machines via normal ssh command line.
+    author: ansible (@core)
+    version_added: historical
+    options:
+        _host:
+            description: Hostname/ip to connect to.
+            default: inventory_hostname
+            host_vars:              
+                 - ansible_host
+                 - ansible_ssh_host
+        _host_key_checking:
+            type: bool
+            description: Determines if ssh should check host keys
+            config:
+                - section: defaults
+                  key: 'host_key_checking'
+            env_vars:
+                - ANSIBLE_HOST_KEY_CHECKING
+        _password:
+            description: Authentication password for the C(remote_user). Can be supplied as CLI option.
+            host_vars:
+                - ansible_password
+                - ansible_ssh_pass
+        _ssh_args:
+            description: Arguments to pass to all ssh cli tools
+            default: '-C -o ControlMaster=auto -o ControlPersist=60s'
+            config:
+                - section: 'ssh_connection'
+                  key: 'ssh_args'
+            env_vars:
+                - ANSIBLE_SSH_ARGS
+        _ssh_common_args:
+            description: Common extra args for ssh CLI tools
+            host_vars:
+                - ansible_ssh_common_args
+        _scp_extra_args:
+            description: Extra exclusive to the 'scp' CLI
+            host_vars:
+                - ansible_scp_extra_args
+        _sftp_extra_args:
+            description: Extra exclusive to the 'sftp' CLI
+            host_vars:
+                - ansible_sftp_extra_args
+        _ssh_extra_args:
+            description: Extra exclusive to the 'ssh' CLI
+            host_vars:
+                - ansible_ssh_extra_args
+        port:
+            description: Remote port to connect to.
+            type: int
+            config:
+               - section: defaults
+                 key: remote_port
+                 default: 22
+            env_vars:
+               - ANSIBLE_REMOTE_PORT
+            host_vars:
+               - ansible_port
+               - 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
+            config:
+               - section: defaults
+                 key: remote_user
+            env_vars:
+               - ANSIBLE_REMOTE_USER
+            host_vars:
+               - ansible_user
+               - ansible_ssh_user
+'''
+
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 

lib/ansible/plugins/lookup/cartesian.py

@@ -14,6 +14,34 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+"""
+DOCUMENTATION:
+    lookup: cartesian
+    version_added: "2.1"
+    short_description: returns the cartesian product of lists
+    description:
+        - Takes the input lists and returns a list that represents the product of the input lists.
+    options:
+        _raw:
+            description:
+                - a set of lists
+            required: True
+EXAMPLES:
+
+  - name: outputs the cartesian product of the supplied lists
+    debug: msg="{{item}}"
+    with_cartesian:
+         - "{{list1}}"
+         - "{{list2}}"
+  - name: used as lookup changes [1, 2, 3], [a, b] into [1, a], [1, b], [2, a], [2, b], [3, a], [3, b]
+    debug: msg="{{ [1,2,3]|lookup('cartesian', [a, b])}}"
+
+RETURN:
+  _list:
+    description:
+      - list of lists composed of elements of the input lists
+    type: lists
+"""
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 

lib/ansible/plugins/lookup/etcd.py

@@ -14,6 +14,43 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+'''
+DOCUMENTATION:
+    author:
+        - Jan-Piet Mens (@jpmens)
+    lookup: etcd
+    version_added: "2.1"
+    short_description: get info from etcd server
+    description:
+        - Retrieves data from an etcd server
+    options:
+        _raw:
+            description:
+                - the list of keys to lookup on the etcd server
+            type: string
+            required: True
+        _etcd_url:
+            description:
+                - Environment variable with the url for the etcd server
+            default: 'http://127.0.0.1:4001'
+            env_vars:
+                - ANSIBLE_ETCD_URL
+        _etcd_version:
+            description:
+                - Environment variable with the etcd protocol version
+            default: 'v1'
+            env_vars:
+                - ANSIBLE_ETCD_VERSION
+EXAMPLES:
+    - name: "a value from a locally running etcd"
+      debug: msg={{ lookup('etcd', 'foo') }}
+RETURN:
+    _list:
+        description:
+            - list of values associated with input keys
+        type: strings
+'''
+
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 

lib/ansible/plugins/strategy/debug.py

@@ -1,3 +1,26 @@
+# 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/>.
+'''
+DOCUMENTATION:
+    strategy: debug
+    short_description: Executes tasks in interactive debug session.
+    description:
+        - Task execution is 'linear' but controlled by an interactive debug session.
+    version_added: "2.1"
+    author: Kishin Yagami
+'''
 
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

lib/ansible/plugins/strategy/free.py

@@ -14,7 +14,17 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-
+'''
+DOCUMENTATION:
+    strategy: free
+    short_description: Executes tasks on each host independently
+    description:
+        - Task execution is as fast as possible per host in batch as defined by C(serial) (default all).
+          Ansible will not wait for other hosts to finish the current task before queuing the next task for a host that has finished.
+          Once a host is done with the play, it opens it's slot to a new host that was waiting to start.
+    version_added: "2.0"
+    author: Ansible Core Team
+'''
 # Make coding more python3-ish
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

lib/ansible/plugins/strategy/linear.py

@@ -14,7 +14,19 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-
+'''
+DOCUMENTATION:
+    strategy: linear
+    short_description: Executes tasks in a linear fashion
+    description:
+        - Task execution is in lockstep per host batch as defined by C(serial) (default all).
+          Up to the fork limit of hosts will execute each task at the same time and then
+          the next series of hosts until the batch is done, before going on to the next task.
+    version_added: "2.0"
+    notes:
+     - This was the default Ansible behaviour before 'strategy plugins' were introduces in 2.0.
+    author: Ansible Core Team
+'''
 # Make coding more python3-ish
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type