diff --git a/docs/bin/plugin_formatter.py b/docs/bin/plugin_formatter.py
index cafc818e34..d50cd9806d 100755
--- a/docs/bin/plugin_formatter.py
+++ b/docs/bin/plugin_formatter.py
@@ -26,7 +26,7 @@ import datetime
 import glob
 import optparse
 import os
-import pprint
+from pprint import PrettyPrinter
 import re
 import sys
 import warnings
@@ -47,6 +47,7 @@ from six import iteritems, string_types
 from ansible.errors import AnsibleError
 from ansible.module_utils._text import to_bytes
 from ansible.utils import plugin_docs
+from ansible.utils.display import Display
 
 
 #####################################################################################
@@ -74,6 +75,9 @@ _CONST = re.compile(r"C\(([^)]+)\)")
 
 DEPRECATED = b" (D)"
 
+pp = PrettyPrinter()
+display = Display()
+
 
 def rst_ify(text):
     ''' convert symbols like I(this is in italics) to valid restructured text '''
@@ -132,13 +136,13 @@ def write_data(text, output_dir, outputname, module=None):
         print(text)
 
 
-def get_module_info(module_dir, limit_to_modules=None, verbose=False):
+def get_plugin_info(module_dir, limit_to=None, verbose=False):
     '''
-    Returns information about modules and the categories that they belong to
+    Returns information about plugins and the categories that they belong to
 
-    :arg module_dir: file system path to the top of the modules directory
-    :kwarg limit_to_modules: If given, this is a list of module names to
-        generate information for.  All other modules will be ignored.
+    :arg module_dir: file system path to the top of the plugin directory
+    :kwarg limit_to: If given, this is a list of plugin names to
+        generate information for.  All other plugins will be ignored.
     :returns: Tuple of two dicts containing module_info, categories, and
         aliases and a set listing deprecated modules:
 
@@ -184,7 +188,7 @@ def get_module_info(module_dir, limit_to_modules=None, verbose=False):
 
         # If requested, limit module documentation building only to passed-in
         # modules.
-        if limit_to_modules is not None and module.lower() not in limit_to_modules:
+        if limit_to is not None and module.lower() not in limit_to:
             continue
 
         deprecated = False
@@ -260,15 +264,15 @@ def generate_parser():
 
     p.add_option("-A", "--ansible-version", action="store", dest="ansible_version", default="unknown", help="Ansible version number")
     p.add_option("-M", "--module-dir", action="store", dest="module_dir", default=MODULEDIR, help="Ansible library path")
-    p.add_option("-P", "--plugin-type", action="store", dest="plugin_type", default='modules', help="The type of plugin (plugins, modules)")
+    p.add_option("-P", "--plugin-type", action="store", dest="plugin_type", default='module', help="The type of plugin (module, lookup, etc)")
     p.add_option("-T", "--template-dir", action="store", dest="template_dir", default="hacking/templates", help="directory containing Jinja2 templates")
     p.add_option("-t", "--type", action='store', dest='type', choices=['rst'], default='rst', help="Document type")
-    p.add_option("-v", "--verbose", action='store_true', default=False, help="Verbose")
     p.add_option("-o", "--output-dir", action="store", dest="output_dir", default=None, help="Output directory for module files")
     p.add_option("-I", "--includes-file", action="store", dest="includes_file", default=None, help="Create a file containing list of processed modules")
-    p.add_option("-l", "--limit-to-modules", action="store", dest="limit_to_modules", default=None,
-                 help="Limit building module documentation to comma-separated list of modules. Specify non-existing module name for no modules.")
+    p.add_option("-l", "--limit-to-modules", '--limit-to', action="store", dest="limit_to", default=None,
+                 help="Limit building module documentation to comma-separated list of plugins. Specify non-existing plugin name for no plugins.")
     p.add_option('-V', action='version', help='Show version number and exit')
+    p.add_option('-v', '--verbose', dest='verbosity', default=0, action="count", help="verbose mode (increase number of 'v's for more)")
     return p
 
 
@@ -287,11 +291,17 @@ def jinja2_environment(template_dir, typ, plugin_type):
         env.filters['fmt'] = rst_fmt
         env.filters['xline'] = rst_xline
         templates['plugin'] = env.get_template('plugin.rst.j2')
-        templates['category_list'] = env.get_template('%s_by_category.rst.j2' % plugin_type)
-        templates['support_list'] = env.get_template('%s_by_support.rst.j2' % plugin_type)
-        templates['list_of_CATEGORY_modules'] = env.get_template('list_of_CATEGORY_%s.rst.j2' % plugin_type)
+
+        if plugin_type == 'module':
+            name = 'modules'
+        else:
+            name = 'plugins'
+
+        templates['category_list'] = env.get_template('%s_by_category.rst.j2' % name)
+        templates['support_list'] = env.get_template('%s_by_support.rst.j2' % name)
+        templates['list_of_CATEGORY_modules'] = env.get_template('list_of_CATEGORY_%s.rst.j2' % name)
     else:
-        raise Exception("unknown module format type: %s" % typ)
+        raise Exception("Unsupported format type: %s" % typ)
 
     return templates
 
@@ -309,22 +319,17 @@ def too_old(added):
     return added_float < TO_OLD_TO_BE_NOTABLE
 
 
-def process_modules(module_map, templates, outputname, output_dir, ansible_version, plugin_type):
+def process_plugins(module_map, templates, outputname, output_dir, ansible_version, plugin_type):
     for module in module_map:
-        # print("rendering: %s" % module)
-
-        # pprint.pprint(('process_modules module:', module))
 
+        display.display("rendering: %s" % module)
         fname = module_map[module]['path']
-
-        # pprint.pprint(('process_modules module_info: ', module_map[module]))
-
-        module_categories = module_map[module].get('categories', [])
+        display.vvvvv(pp.pformat(('process_plugins info: ', module_map[module])))
 
         # crash if module is missing documentation and not explicitly hidden from docs index
         if module_map[module]['doc'] is None:
-            print("%s: ERROR: MODULE MISSING DOCUMENTATION" % (fname,))
-            _doc = {'module': module,
+            display.error("%s MISSING DOCUMENTATION" % (fname,))
+            _doc = {plugin_type: module,
                     'version_added': '2.4',
                     'filename': fname}
             module_map[module]['doc'] = _doc
@@ -332,8 +337,7 @@ def process_modules(module_map, templates, outputname, output_dir, ansible_versi
 
         # Going to reference this heavily so make a short name to reference it by
         doc = module_map[module]['doc']
-
-        # pprint.pprint(('process_modules doc: ', doc))
+        display.vvvvv(pp.pformat(('process_plugins doc: ', doc)))
 
         # add some defaults for plugins that dont have most of the info
         doc['module'] = doc.get('module', module)
@@ -342,12 +346,12 @@ def process_modules(module_map, templates, outputname, output_dir, ansible_versi
         doc['plugin_type'] = plugin_type
 
         if module_map[module]['deprecated'] and 'deprecated' not in doc:
-            print("%s: WARNING: MODULE MISSING DEPRECATION DOCUMENTATION: %s" % (fname, 'deprecated'))
+            display.warning("%s PLUGIN MISSING DEPRECATION DOCUMENTATION: %s" % (fname, 'deprecated'))
 
         required_fields = ('short_description',)
         for field in required_fields:
             if field not in doc:
-                print("%s: WARNING: MODULE MISSING field '%s'" % (fname, field))
+                display.warning("%s PLUGIN MISSING field '%s'" % (fname, field))
 
         not_nullable_fields = ('short_description',)
         for field in not_nullable_fields:
@@ -355,8 +359,7 @@ def process_modules(module_map, templates, outputname, output_dir, ansible_versi
                 print("%s: WARNING: MODULE field '%s' DOCUMENTATION is null/empty value=%s" % (fname, field, doc[field]))
 
         if 'version_added' not in doc:
-            pprint.pprint(doc)
-            # sys.exit("*** ERROR: missing version_added in: %s ***\n" % module)
+            display.error("*** ERROR: missing version_added in: %s ***\n" % module)
 
         #
         # The present template gets everything from doc so we spend most of this
@@ -424,7 +427,7 @@ def process_modules(module_map, templates, outputname, output_dir, ansible_versi
 
         doc['metadata'] = module_map[module]['metadata']
 
-        # pprint.pprint(module_map[module]
+        display.vvvvv(pp.pformat(module_map[module]))
         if module_map[module]['returndocs']:
             try:
                 doc['returndocs'] = yaml.safe_load(module_map[module]['returndocs'])
@@ -438,29 +441,18 @@ def process_modules(module_map, templates, outputname, output_dir, ansible_versi
         if isinstance(doc['author'], string_types):
             doc['author'] = [doc['author']]
 
-        # print('about to template')
-        # pprint.pprint(doc)
+        display.v('about to template %s' % module)
+        display.vvvvv(pp.pformat(doc))
         text = templates['plugin'].render(doc)
-
-        # plugins get namespace dirs but modules do not
-        if plugin_type == 'plugins':
-            for module_category in module_categories:
-                category_output_dir = os.path.join(output_dir, 'plugins', '%s' % module_category)
-                write_data(text, category_output_dir, outputname, module)
-        else:
-                write_data(text, output_dir, outputname, module)
+        write_data(text, output_dir, outputname, module)
 
 
-def process_categories(mod_info, categories, templates,
-                       output_dir, output_name, plugin_type):
+def process_categories(plugin_info, categories, templates, output_dir, output_name, plugin_type):
     for category in sorted(categories.keys()):
-        if (plugin_type, category) == ('plugins', ''):
-            print('skipping unknown cat: %s' % category)
-            continue
         module_map = categories[category]
         category_filename = output_name % category
 
-        print("*** recording category %s in %s ***" % (category, category_filename))
+        display.display("*** recording category %s in %s ***" % (category, category_filename))
 
         # start a new category file
 
@@ -472,7 +464,7 @@ def process_categories(mod_info, categories, templates,
                          'category_name': category_name,
                          'category': module_map,
                          'subcategories': subcategories,
-                         'module_info': mod_info,
+                         'module_info': plugin_info,
                          'plugin_type': plugin_type
                          }
 
@@ -480,7 +472,7 @@ def process_categories(mod_info, categories, templates,
         write_data(text, output_dir, category_filename)
 
 
-def process_support_levels(mod_info, templates, output_dir, plugin_type):
+def process_support_levels(plugin_info, templates, output_dir, plugin_type):
     supported_by = {'Ansible Core Team': {'slug': 'core_supported',
                                           'modules': [],
                                           'output': 'core_maintained.rst',
@@ -528,9 +520,9 @@ These modules are currently shipped with Ansible, but will most likely be shippe
     if plugin_type == 'plugins':
         return
     # Separate the modules by support_level
-    for module, info in mod_info.items():
+    for module, info in plugin_info.items():
         if not info.get('metadata', None):
-            print('no metadata for %s' % module)
+            display.warning('no metadata for %s' % module)
             continue
         if info['metadata']['supported_by'] == 'core':
             supported_by['Ansible Core Team']['modules'].append(module)
@@ -548,7 +540,7 @@ These modules are currently shipped with Ansible, but will most likely be shippe
         template_data = {'maintainers': maintainers,
                          'modules': data['modules'],
                          'slug': data['slug'],
-                         'module_info': mod_info,
+                         'module_info': plugin_info,
                          }
         text = templates['support_list'].render(template_data)
         write_data(text, output_dir, data['output'])
@@ -567,62 +559,72 @@ def validate_options(options):
 
 def main():
 
+    # INIT
     p = generate_parser()
-
     (options, args) = p.parse_args()
     validate_options(options)
-
+    display.verbosity = options.verbosity
     plugin_type = options.plugin_type
 
-    if plugin_type == 'modules':
-        templates = jinja2_environment(options.template_dir, options.type, plugin_type)
-        output_dir = options.output_dir
+    # prep templating
+    templates = jinja2_environment(options.template_dir, options.type, plugin_type)
+
+    # set file/directory structure
+    if plugin_type == 'module':
         # trim trailing s off of plugin_type for plugin_type=='modules'. ie 'copy_module.rst'
-        outputname = '%s_' + '%s.rst' % plugin_type[:-1]
+        outputname = '%s_' + '%s.rst' % plugin_type
+        output_dir = options.output_dir
     else:
-        templates = jinja2_environment(options.template_dir, options.type, 'plugins')
         # for plugins, just use 'ssh.rst' vs 'ssh_module.rst'
         outputname = '%s.rst'
         output_dir = '%s/plugins/%s' % (options.output_dir, plugin_type)
 
-    # Convert passed-in limit_to_modules to None or list of modules.
-    if options.limit_to_modules is not None:
-        options.limit_to_modules = [s.lower() for s in options.limit_to_modules.split(",")]
+    display.vv('output name: %s' % outputname)
+    display.vv('output dir: %s' % output_dir)
 
-    mod_info, categories = get_module_info(options.module_dir, limit_to_modules=options.limit_to_modules, verbose=options.verbose)
+    # Convert passed-in limit_to to None or list of modules.
+    if options.limit_to is not None:
+        options.limit_to = [s.lower() for s in options.limit_to.split(",")]
 
-    categories['all'] = {'_modules': mod_info.keys()}
+    plugin_info, categories = get_plugin_info(options.module_dir, limit_to=options.limit_to, verbose=(options.verbosity > 0))
+
+    categories['all'] = {'_modules': plugin_info.keys()}
+
+    display.vvv(pp.pformat(categories))
+    display.vvvvv(pp.pformat(plugin_info))
 
-    # pprint.pprint(categories)
-    # pprint.pprint(mod_info)
-    # pprint.pprint(dict(mod_info))
     # Transform the data
     if options.type == 'rst':
-        for key, record in mod_info.items():
-            # pprint.pprint(('record', record))
+        display.v('Generating rst')
+        for key, record in plugin_info.items():
+            display.vv(key)
+            display.vvvvv(pp.pformat(('record', record)))
             if record.get('doc', None):
                 short_desc = record['doc']['short_description']
                 if short_desc is None:
-                    print('WARNING: short_description for %s is None' % key)
+                    display.warning('short_description for %s is None' % key)
                     short_desc = ''
                 record['doc']['short_description'] = rst_ify(short_desc)
 
-    if plugin_type == 'modules':
-        # Write master category list
+    if plugin_type == 'module':
+        display.v('Generating Categories')
+        # Write module master category list
         category_list_text = templates['category_list'].render(categories=sorted(categories.keys()))
-        category_index_name = '%s_by_category.rst' % plugin_type
+        category_index_name = '%ss_by_category.rst' % plugin_type
         write_data(category_list_text, output_dir, category_index_name)
 
-    # Render all the individual module pages
-    process_modules(mod_info, templates, outputname, output_dir, options.ansible_version, plugin_type)
+    # Render all the individual plugin pages
+    display.v('Generating plugin pages')
+    process_plugins(plugin_info, templates, outputname, output_dir, options.ansible_version, plugin_type)
 
     # Render all the categories for modules
-    if plugin_type == 'modules':
-        category_list_name_template = 'list_of_%s_' + '%s.rst' % plugin_type
-        process_categories(mod_info, categories, templates, output_dir, category_list_name_template, plugin_type)
+    if plugin_type == 'module':
+        display.v('Generating Category lists')
+        category_list_name_template = 'list_of_%s_' + '%ss.rst' % plugin_type
+        process_categories(plugin_info, categories, templates, output_dir, category_list_name_template, plugin_type)
 
         # Render all the categories for modules
-        process_support_levels(mod_info, templates, output_dir, plugin_type)
+        process_support_levels(plugin_info, templates, output_dir, plugin_type)
 
 
 if __name__ == '__main__':
diff --git a/docs/docsite/Makefile b/docs/docsite/Makefile
index eed766e45c..1c5522dda1 100644
--- a/docs/docsite/Makefile
+++ b/docs/docsite/Makefile
@@ -32,7 +32,7 @@ all: docs
 
 docs: clean htmldocs
 
-generate_rst: testing keywords modules plugins staticmin cli config
+generate_rst: staticmin config cli keywords modules plugins testing
 
 htmldocs: generate_rst
 	CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx html
diff --git a/docs/docsite/rst/playbooks_lookups.rst b/docs/docsite/rst/playbooks_lookups.rst
index 3dce6b2f49..e1e355b9e1 100644
--- a/docs/docsite/rst/playbooks_lookups.rst
+++ b/docs/docsite/rst/playbooks_lookups.rst
@@ -18,9 +18,8 @@ Lookup plugins allow access to outside data sources. Like all templating, these
 Lookups and loops
 `````````````````
 
-Various *lookup plugins* allow additional ways to iterate over data.
-In :doc:`Loops <playbooks_loops>` you will learn how to use them to walk over collections of numerous types.
-However, they can also be used to pull in data from remote sources, such as shell commands or even key value stores.
+*lookup plugins* are a way to query external data sources, such as shell commands or even key value stores.
+
 Before Ansible 2.5, lookups were mostly used indirectly in ``with_<lookup`` constructes for looping, begining in 2.5
 we use them more explicitly as part of Jinja2 expressions fed into the ``loop`` keyword.
 
@@ -37,6 +36,8 @@ One way of using lookups is to populate variables. These macros are evaluated ea
     tasks:
       - debug: msg="motd value is {{ motd_value }}"
 
+For more details and a complete list of lookup plugins available, please see :doc:`plugins/lookup`.
+
 .. seealso::
 
    :doc:`playbooks`
diff --git a/docs/docsite/rst/plugins/action.rst b/docs/docsite/rst/plugins/action.rst
index be35bc647b..1c84b4fb48 100644
--- a/docs/docsite/rst/plugins/action.rst
+++ b/docs/docsite/rst/plugins/action.rst
@@ -6,11 +6,20 @@ They usually execute automatically in the background doing prerequisite work bef
 
 The 'normal' action plugin is used for modules that do not already have an action plugin.
 
+.. _enabling_action:
+
 Enabling Action Plugins
 +++++++++++++++++++++++
 
 You can enable a custom action plugin by either dropping it into the ``action_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the action plugin directory sources configured in :doc:`ansible.cfg <../config>`.
 
+.. _using_action:
+
+Using Action Plugins
++++++++++++++++++++++
+
+Action plugin are executed by default when an associated module is used; no action is required.
+
 .. seealso::
 
    :doc:`cache`
diff --git a/docs/docsite/rst/plugins/cache.rst b/docs/docsite/rst/plugins/cache.rst
index 82eec09271..43ba9b2dfa 100644
--- a/docs/docsite/rst/plugins/cache.rst
+++ b/docs/docsite/rst/plugins/cache.rst
@@ -10,11 +10,12 @@ without the performance hit of retrieving them from source.
 The default cache plugin is the :doc:`memory <cache/memory>` plugin, which only caches the data for the current execution of Ansible. Other plugins with persistent storage are available to allow caching the data across runs.
 
 
+.. _enabling_cache:
+
 Enabling Cache Plugins
 ++++++++++++++++++++++
 
 Only one cache plugin can be active at a time.
-
 You can enable a cache plugin in the Ansible configuration, either via environment variable:
 
 .. code-block:: shell
@@ -31,10 +32,23 @@ or in the ``ansible.cfg`` file:
 You will also need to configure other settings specific to each plugin. Consult the individual plugin documentation
 or the Ansible :doc:`configuration <../config>` for more details.
 
+A custom cache plugin is enabled by dropping it into a ``cache_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the directory sources configured in :doc:`ansible.cfg <../config>`.
+
+
+.. _using_cache:
+
+Using Cache Plugins
++++++++++++++++++++
+
+Cache plugins are used autoamtically once they are enabled.
+
+
+.. _cache_plugin_list:
+
 Plugin List
 +++++++++++
 
-You can use ``ansible-doc -t cache -l`` to see the list of available plugins. 
+You can use ``ansible-doc -t cache -l`` to see the list of available plugins.
 Use ``ansible-doc -t cache <plugin name>`` to see specific documentation and examples.
 
 .. toctree:: :maxdepth: 1
diff --git a/docs/docsite/rst/plugins/callback.rst b/docs/docsite/rst/plugins/callback.rst
index 1ab416233a..9e3c295a50 100644
--- a/docs/docsite/rst/plugins/callback.rst
+++ b/docs/docsite/rst/plugins/callback.rst
@@ -70,6 +70,8 @@ You can also set this as an environment variable:
     export ANSIBLE_LOAD_CALLBACK_PLUGINS=1
 
 
+.. _callback_plugin_list:
+
 Plugin List
 +++++++++++
 
diff --git a/docs/docsite/rst/plugins/connection.rst b/docs/docsite/rst/plugins/connection.rst
index 14f2ffaaf1..8baaa12e77 100644
--- a/docs/docsite/rst/plugins/connection.rst
+++ b/docs/docsite/rst/plugins/connection.rst
@@ -11,7 +11,6 @@ By default, Ansible ships with several plugins. The most commonly used are the '
 The basics of these connection types are covered in the :doc:`../intro_getting_started` section.  
 
 
-.. contents:: Topics
 
 .. _ssh_plugins:
 
@@ -20,28 +19,7 @@ ssh Plugins
 
 Because ssh is the default protocol used in system administration and the protocol most used in Ansible, ssh options are included in the command line tools. See :doc:`../ansible-playbook` for more details.
 
-
-.. _using_connection_plugins:
-
-Using Connection Plugins
-++++++++++++++++++++++++
-
-The transport can be changed via :doc:`configuration <../config>`, in the command line (``-c``, ``--connection``), as a keyword (:ref:`connection`)
-in your play or by setting the a connection variable (:ref:`ansible_connection`), most often, in your inventory.
-For example, for windows machines you might want o use the :doc:`winrm <connection/winrm>` plugin instead.
-
-Most connection plugins can operate with a minimum configuration. By default they use the :ref:`inventory_hostname` and defaults to find the target host.
-
-Plugins are self-documenting. Each plugin should document its configuration options. The following are connection variables common to most connection plugins:
-
-:ref:ansible_host
-    The name of the host to connect to, if different from the :ref:`inventory_hostname`.
-:ref:ansible_port
-    The ssh port number. For :doc:`ssh <connection/ssh>` and :doc:`paramiko <connection/paramiko>` the default value is 22.
-:ref:ansible_user
-    The default user name to use for log in. Most plugins default to the current user running Ansible.
-
-Each plugin might also have a specific version of a variable that overrides the general version. For example, :ref:`ansible_ssh_host` for the :doc:`ssh <connection/ssh>` plugin.
+.. _enabling_connection:
 
 Enabling Connection Plugins
 +++++++++++++++++++++++++++
@@ -49,6 +27,31 @@ Enabling Connection Plugins
 You can extend Ansible to support other transports (such as SNMP or message bus) by dropping a custom plugin
 into the ``connection_plugins`` directory.
 
+
+.. _using_connection:
+
+Using Connection Plugins
+++++++++++++++++++++++++
+
+The transport can be changed via :doc:`configuration <../config>`, in the command line (``-c``, ``--connection``), as a keyword (:ref:`connection`)
+in your play, or by setting the a connection variable (:ref:`ansible_connection`), most often in your inventory.
+For example, for Windows machines you might want to use the :doc:`winrm <connection/winrm>` plugin.
+
+Most connection plugins can operate with a minimum configuration. By default they use the :ref:`inventory_hostname` and defaults to find the target host.
+
+Plugins are self-documenting. Each plugin should document its configuration options. The following are connection variables common to most connection plugins:
+
+:ref:`ansible_host`
+    The name of the host to connect to, if different from the :ref:`inventory_hostname`.
+:ref:`ansible_port`
+    The ssh port number, for :doc:`ssh <connection/ssh>` and :doc:`paramiko <connection/paramiko>` it defaults to 22.
+:ref:`ansible_user`
+    The default user name to use for log in. Most plugins default to the 'current user running Ansible'.
+
+Each plugin might also have a specific version of a variable that overrides the general version. For example, :ref:`ansible_ssh_host` for the :doc:`ssh <connection/ssh>` plugin.
+
+.. _connection_plugin_list:
+
 Plugin List
 +++++++++++
 
diff --git a/docs/docsite/rst/plugins/inventory.rst b/docs/docsite/rst/plugins/inventory.rst
index b9ed30c70c..588bd1bb2c 100644
--- a/docs/docsite/rst/plugins/inventory.rst
+++ b/docs/docsite/rst/plugins/inventory.rst
@@ -6,7 +6,8 @@ Inventory Plugins
 
 Inventory plugins allow users to point at data sources to compile the inventory of hosts that Ansible uses to target tasks, either via the ``-i /path/to/file`` and/or ``-i 'host1, host2`` command line parameters or from other configuration sources.
 
-.. _enabling_inventory_plugins:
+
+.. _enabling_inventory:
 
 Enabling Inventory Plugins
 ++++++++++++++++++++++++++
@@ -28,6 +29,18 @@ This list also establishes the order in which each plugin tries to parse an inve
    enable_plugins = advanced_host_list, constructed, yaml
 
 
+.. _using_inventory:
+
+Using Inventory Plugins
++++++++++++++++++++++++
+
+The only requirement for using an inventory plugin after it is enabled is to provide an inventory source to parse.
+Ansible will try to use the list of enabled inventory plugins, in order, against each inventory source provided.
+Once an inventory plugin succeeds at parsing a source, the any remaining inventory plugins will be skipped for that source.
+
+
+.. _inventory_plugin_list:
+
 Plugin List
 +++++++++++
 
diff --git a/docs/docsite/rst/plugins/lookup.rst b/docs/docsite/rst/plugins/lookup.rst
new file mode 100644
index 0000000000..691c806ff6
--- /dev/null
+++ b/docs/docsite/rst/plugins/lookup.rst
@@ -0,0 +1,99 @@
+.. contents:: Topics
+
+
+Lookup Plugins
+--------------
+
+Lookup plugins allow Ansible to access data from outside sources.
+This can include reading the filesystem in addition to contacting external datastores and services.
+Like all templating, these plugins are evaluated on the Ansible control machine, not on the target/remote.
+
+The data returned by a lookup plugin is made available using the standard templating system in Ansible,
+and are typically used to load variables or templates with information from those systems.
+
+Lookups are an Ansible-specific extension to the Jinja2 templating language.
+
+.. note::
+   - Lookups are executed with a working directory relative to the role or play,
+     as opposed to local tasks, which are executed relative the executed script.
+   - Since Ansible version 1.9, you can pass wantlist=True to lookups to use in Jinja2 template "for" loops.
+   - Lookup plugins are an advanced feature; to best leverage them you should have a good working knowledge of how to use Ansible plays.  
+
+.. warning::
+   - Some lookups pass arguments to a shell. When using variables from a remote/untrusted source, use the `|quote` filter to ensure safe usage.
+
+
+.. _enabling_lookup:
+
+Enabling Lookup Plugins
++++++++++++++++++++++++
+
+You can activate a custom lookup by either dropping it into a ``lookup_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the lookup directory sources configured in :doc:`ansible.cfg <../config>`.
+
+
+.. _using_lookup:
+
+Using Lookup Plugins
+++++++++++++++++++++
+
+Lookup plugins can be used anywhere you can use templating in Ansible: in a play, in variables file, or in a Jinja2 template for the :doc:`template <../template_module>` module.
+
+.. code-block:: yaml
+
+  vars:
+    file_contents: "{{lookup('file', 'path/to/file.txt')}}"
+
+Lookups are an integral part of loops. Wherever you see ``with_``, the part after the underscore is the name of a lookup.
+This is also the reason most lookups output lists and take lists as input; for example, ``with_items`` uses the :doc:`items <lookup/items>` lookup:
+
+.. code-block:: yaml
+
+  tasks:
+    - name: count to 3
+      debug: msg={{item}}
+      with_items: [1, 2, 3]
+
+You can combine lookups with :doc:`../playbooks_filters`, :doc:`../playbooks_tests` and even each other to do some complex data generation and maniplulation. For example:
+
+.. code-block:: yaml
+
+  tasks:
+    - name: valid but useless and over complicated chained lookups and filters
+      debug: msg="find the answer here:\n{{ lookup('url', 'http://google.com/search/?q=' + item|urlencode)|join(' ') }}"
+      with_nested:
+        - "{{lookup('consul_kv', 'bcs/' + lookup('file', '/the/question') + ', host=localhost, port=2000')|shuffle}}"
+        - "{{lookup('sequence', 'end=42 start=2 step=2')|map('log', 4)|list)}}"
+        - ['a', 'c', 'd', 'c']
+
+
+.. _lookup_plugins_list:
+
+Plugin List
++++++++++++
+
+You can use ``ansible-doc -t lookup -l`` to see the list of available plugins. Use ``ansible-doc -t lookup <plugin name>`` to see specific documents and examples.
+
+
+.. toctree:: :maxdepth: 1
+    :glob:
+
+    lookup/*
+
+.. seealso::
+
+   :doc:`../playbooks`
+       An introduction to playbooks
+   :doc:`inventory`
+       Ansible inventory plugins
+   :doc:`callback`
+       Ansible callback plugins
+   :doc:`../playbooks_filters`
+       Jinja2 filter plugins
+   :doc:`../playbooks_tests`
+       Jinja2 test plugins
+   :doc:`../playbooks_lookups`
+       Jinja2 lookup plugins
+   `User Mailing List <http://groups.google.com/group/ansible-devel>`_
+       Have a question?  Stop by the google group!
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible IRC chat channel
diff --git a/docs/docsite/rst/plugins/shell.rst b/docs/docsite/rst/plugins/shell.rst
index 56ae0f9ca2..7462a565f0 100644
--- a/docs/docsite/rst/plugins/shell.rst
+++ b/docs/docsite/rst/plugins/shell.rst
@@ -1,15 +1,27 @@
 Shell Plugins
 -------------
 
-Shell plugins work transparently to ensure that the basic commands Ansible runs are properly formated to work with the target machine.
+Shell plugins work transparently to ensure that the basic commands Ansible runs are properly formatted to work with the target machine.
+
+.. _enabling_shell:
 
 Enabling Shell Plugins
 ++++++++++++++++++++++
 
-.. warning:: These plugins should not be reconfigured unless you have a restricted or exotic setup
-             in which the default ``/bin/sh`` is not a POSIX compatible shell or not availble for execution. 
+You can add a custom shell plugin by dropping it into a ``shell_plugins`` directory adjacent to your play, inside a role,
+or by putting it in one of the shell plugin directory sources configured in :doc:`ansible.cfg <../config>`.
 
-In addition to modifying the default configuration settings in :doc:`../config`, you can use a 'connection variable' :ref:`ansible_shell_type` to select a shell plugin, and update the :ref:`ansible_executable` to match.
+.. warning:: You should not alter the configuration for these plugins unless you have a setup
+             in which the default ``/bin/sh`` is not a POSIX compatible shell or is not availble for execution.
+
+.. _using_shell:
+
+Using Shell Plugins
++++++++++++++++++++
+
+In addition to the default configuration settings in :doc:`../config`,
+you can use a 'connection variable' :ref:`ansible_shell_type` to select the plugin to use. 
+In this case, you will also want to update the :ref:`ansible_executable` to match.
 
 .. seealso::
 
diff --git a/docs/docsite/rst/plugins/strategy.rst b/docs/docsite/rst/plugins/strategy.rst
index 046f050fa7..5e3bb97814 100644
--- a/docs/docsite/rst/plugins/strategy.rst
+++ b/docs/docsite/rst/plugins/strategy.rst
@@ -6,11 +6,21 @@ Strategy Plugins
 
 Strategy plugins control the flow of play execution by handling task and host scheduling.
 
+.. _enable_strategy:
 
 Enabling Strategy Plugins
 +++++++++++++++++++++++++
 
-Only one strategy plugin can be used in a play, but you can use different ones for each play in a playbook or Ansible run.
+Strategy plugins shipped with Ansible are enabled by default. You can enable a custom strategy plugin by
+putting it in one of the lookup directory sources configured in :doc:`ansible.cfg <../config>`.
+
+
+.. _using_strategy:
+
+Using Strategy Plugins
+++++++++++++++++++++++
+
+Only one strategy plugin can be used in a play, but you can use different ones for each play in a playbook or ansible run.
 The default is the :doc:`linear <strategy/linear>` plugin. You can change this default in Ansible :doc:`configuration <../config>` using an environment variable:
 
 .. code-block:: shell
@@ -38,6 +48,7 @@ You can also specify the strategy plugin in the play via the :ref:`strategy` key
       - name: restart_tomcat
         service: name=tomcat state=restarted
 
+.. _strategy_plugin_list:
 
 Plugin List
 +++++++++++
diff --git a/docs/docsite/rst/plugins/vars.rst b/docs/docsite/rst/plugins/vars.rst
index d1614be83c..a002eff5a1 100644
--- a/docs/docsite/rst/plugins/vars.rst
+++ b/docs/docsite/rst/plugins/vars.rst
@@ -11,11 +11,24 @@ Vars plugins were partially implented in Ansible 2.0 and rewritten to be fully i
 The :doc:`host_group_vars <vars/host_group_vars>` plugin shipped with Ansible enables reading variables from :ref:`host_vars` and :ref:`group_vars`.
 
 
+.. _enable_vars:
+
 Enabling Vars Plugins
 +++++++++++++++++++++
 
 You can activate a custom vars plugins by either dropping it into a ``vars_plugins`` directory adjacent to your play,  inside a role, or by putting it in one of the directory sources configured in :doc:`ansible.cfg <../config>`.
 
+
+.. _using_vars:
+
+Using Vars Plugins
+++++++++++++++++++
+
+Vars plugins are used automatically after they are enabled.
+
+
+.. _vars_plugin_list:
+
 Plugin Lists
 ++++++++++++
 
diff --git a/docs/templates/config.rst.j2 b/docs/templates/config.rst.j2
index e3ffa531b8..3df3bf0ba6 100644
--- a/docs/templates/config.rst.j2
+++ b/docs/templates/config.rst.j2
@@ -15,7 +15,7 @@ where their current value comes from. See :doc:ansible-config for more informati
 The configuration file
 ======================
 
-Changes can be made and used in a configuration file which will be searched for in the following order::
+Changes can be made and used in a configuration file which will be searched for in the following order:
 
  * ANSIBLE_CONFIG (environment variable if set)
  * ansible.cfg (in the current directory)
diff --git a/docs/templates/list_of_CATEGORY_modules.rst.j2 b/docs/templates/list_of_CATEGORY_modules.rst.j2
index 7fcf01f0a9..3323fd5c83 100644
--- a/docs/templates/list_of_CATEGORY_modules.rst.j2
+++ b/docs/templates/list_of_CATEGORY_modules.rst.j2
@@ -1,4 +1,4 @@
-@{ title }@ @{ plugin_type }@
+@{ title }@ @{ plugin_type + 's' }@
 @{ '`' * title | length }@````````
 
 {% if blurb %}
diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2
index 392a3911ba..7b1e4163d5 100644
--- a/docs/templates/plugin.rst.j2
+++ b/docs/templates/plugin.rst.j2
@@ -58,20 +58,22 @@ Aliases: @{ ','.join(aliases) }@
 
 
 {% endif %}
-{% if requirements %}
-
-Requirements (on host that executes module)
--------------------------------------------
 
 {% if requirements %}
+{% set req = 'Requirements' %}
+{% if plugin_type == 'module' %}
+{% set req = req + ' (on host that executes module)' %}
+{% endif %}
+{% set req_len = req|length %}
+@{ req }@
+@{ '-' * req_len }@
+
 {% for req in requirements %}
   * @{ req | convert_symbols_to_format }@
 {% endfor %}
 
 {% endif %}
 
-
-{% endif %}
 {% if options -%}
 
 
@@ -87,6 +89,9 @@ Options
     <th class="head">required</th>
     <th class="head">default</th>
     <th class="head">choices</th>
+{% if plugin_type != 'module' %}
+    <th class="head">configuration</th>
+{% endif %}
     <th class="head">comments</th>
     </tr>
 {% for k in option_keys -%}
@@ -102,23 +107,48 @@ Options
 {% else %}
     <td>{% if v['choices'] -%}<ul>{% for choice in v.get('choices',[]) -%}<li>@{ choice }@</li>{% endfor -%}</ul>{% endif -%}</td>
 {% endif %}
+{% if plugin_type != 'module' %}
     <td>
+	{% if 'ini' in v %}
+	<div> ini entries:
+	{% for ini in v.get('ini') %}
+        <p>[@{ ini.section }@ ]<br>@{ ini.key}@ = @{ v['default']|default('VALUE') }@</p>
+	{% endfor %}
+	</div>
+	{% endif %}
+	{% if 'env' in v %}
+	{% for env in v.get('env') %}
+        <div>env:@{ env.name }@</div>
+	{% endfor %}
+	{% endif %}
+	{% if 'vars' in v %}
+	{% for myvar in v.get('vars') %}
+        <div>var: @{ myvar.name }@</div>
+	{% endfor %}
+	{% endif %}
+	</td>
+{% endif %}
+	<td>
 {% if v.description is string %}
         <div>@{ v.description | replace('\n', '\n    ') | html_ify }@</div>
 {% else %}
 {% for desc in v.description %}
-        <div>@{ desc | replace('\n', '\n    ') | html_ify }@</div>
+        <p>@{ desc | replace('\n', '\n    ') | html_ify }@</p>
 {% endfor %}
 {% endif %}
 {% if 'aliases' in v and v.aliases %}
         </br><div style="font-size: small;">aliases: @{ v.aliases|join(', ') }@</div>
 {% endif %}
+	</td>
+	</tr>
 {% else %}
-
     <tr>
     <td rowspan="2">@{ k }@<br/><div style="font-size: small;">{% if v['version_added'] -%} (added in @{v['version_added']}@){% endif -%}</div></td>
     <td>{% if v.get('required', False) -%}yes{% else -%}no{% endif -%}</td>
     <td></td>
+{% if plugin_type != 'module' %}
+    <td></td>
+{% endif %}
     <td></td>
     <td>
 {% for desc in v.description %}
@@ -187,7 +217,7 @@ Options
 Examples
 --------
 
- ::
+.. code-block:: yaml
 
 {% for example in examples %}
 {% if example['description'] %}@{ example['description'] | indent(4, True) }@{% endif %}
@@ -203,7 +233,7 @@ Examples
 Return Values
 -------------
 
-Common return values are documented :ref:`here <common_return_values>`, the following are the fields unique to this module:
+Common return values are documented :ref:`here <common_return_values>`, the following are the fields unique to this {{plugin_type}}:
 
 .. raw:: html
 
@@ -265,16 +295,12 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
         <td align=center>@{ returndocs[entry].contains[sub].sample }@</td>
         </tr>
 {% endfor %}
-
         </table>
-    </td>
-    </tr>
+	</td></tr>
 {% endif %}
 {% endfor %}
-
     </table>
-    </br>
-    </br>
+    </br></br>
 {% endif %}
 
 
@@ -325,12 +351,13 @@ This module is flagged as **@{cur_state}@** which means that @{module_states[cur
 Maintenance Info
 ~~~~~~~~~~~~~~~~
 
-For more information about Red Hat's this support of this module, please
-refer to this `knowledge base article<https://access.redhat.com/articles/rhel-top-support-policies>`_
+For more information about Red Hat's this support of this @{ plugin_type }@,
+please refer to this `knowledge base article<https://access.redhat.com/articles/rhel-top-support-policies>_`
 
 {% endif %}
 {% endif %}
 {% endif %}
 
-For help in developing on modules, should you be so inclined, please read :doc:`../../community`, :doc:`../../dev_guide/testing` and :doc:`../../dev_guide/developing_modules`.
+For help in developing, should you be so inclined, please read :doc:`../../community`,
+:doc:`../../dev_guide/testing` and {% if plugin_type == 'module' %}:doc:`../../dev_guide/developing_modules`{% else %}:doc:`../../dev_guide/developing_plugins`{% endif %}.
 
diff --git a/lib/ansible/plugins/inventory/openstack.py b/lib/ansible/plugins/inventory/openstack.py
index 0aa59e86c1..fae78185bc 100644
--- a/lib/ansible/plugins/inventory/openstack.py
+++ b/lib/ansible/plugins/inventory/openstack.py
@@ -11,6 +11,9 @@ __metaclass__ = type
 DOCUMENTATION = '''
     name: openstack
     plugin_type: inventory
+    authors:
+      - Marco Vito Moscaritolo <marco@agavee.com>
+      - Jesse Keating <jesse.keating@rackspace.com>
     short_description: OpenStack inventory source
     description:
         - Get inventory hosts from OpenStack clouds