allow config for callbaks and some fixes

* only complain about ini deprecation if value is set
 * set plugin config for stdout and other types
 * updated plugin docs, moved several plugins to new config
 * finished ssh docs
 * fixed some issues seen in plugins while modifying docs
 * placeholder for 'required'
 * callbacks must use _plugin_options as _options already in use

lib/ansible/plugins/callback/selective.py

@@ -1,61 +1,59 @@
 # (c) Fastly, inc 2016
-#
-# 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/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 """
-selective.py callback plugin.
-
-This callback only prints tasks that have been tagged with `print_action` or that have failed.
-Tasks that are not printed are placed with a '.'.
-
-For example:
-
-- debug: msg="This will not be printed"
-- debug: msg="But this will"
-  tags: [print_action]"
-
-This allows operators to focus on the tasks that provide value only.
-
-If you increase verbosity all tasks are printed.
+DOCUMENTATION:
+    callback: selective
+    callback_type: stdout
+    requirements:
+      - set as main display callback
+    short_description: only print certain tasks
+    version_added: "2.4"
+    description:
+      - This callback only prints tasks that have been tagged with `print_action` or that have failed.
+        This allows operators to focus on the tasks that provide value only.
+      - Tasks that are not printed are placed with a '.'.
+      - If you increase verbosity all tasks are printed.
+    options:
+      nocolor:
+        default: False
+        description: This setting allows suppressing colorizing output
+        env:
+          - name: ANSIBLE_NOCOLOR
+          - name: ANSIBLE_SELECTIVE_DONT_COLORIZE
+        ini:
+          - section: defaults
+          - key: nocolor
+        type: boolean
+EXAMPLES:
+  - debug: msg="This will not be printed"
+  - debug: msg="But this will"
+    tags: [print_action]
 """
 
 from __future__ import (absolute_import, division, print_function)
 
 import difflib
-import os
 
+from ansible import constants as C
 from ansible.plugins.callback import CallbackBase
 from ansible.module_utils._text import to_text
 
 __metaclass__ = type
 
-
+DONT_COLORIZE = False
 COLORS = {
     'normal': '\033[0m',
-    'ok': '\033[92m',
+    'ok': C.COLOR_OK,
     'bold': '\033[1m',
     'not_so_bold': '\033[1m\033[34m',
-    'changed': '\033[93m',
-    'failed': '\033[91m',
+    'changed': C.COLOR_CHANGED,
+    'failed': C.COLOR_ERROR,
     'endc': '\033[0m',
-    'skipped': '\033[96m',
+    'skipped': C.COLOR_SKIP,
 }
 
-DONT_COLORIZE = os.getenv('ANSIBLE_SELECTIVE_DONT_COLORIZE', default=False)
-
 
 def dict_diff(prv, nxt):
     """Return a dict of keys that differ with another config object."""
@@ -89,6 +87,13 @@ class CallbackModule(CallbackBase):
         self.last_task_name = None
         self.printed_last_task = False
 
+    def set_options(self, options):
+
+        super(CallbackModule, self).set_options(options)
+
+        global DONT_COLORIZE
+        DONT_COLORIZE = self._plugin_options['nocolor']
+
     def _print_task(self, task_name=None):
         if task_name is None:
             task_name = self.last_task_name