Document vault and make some cross-references in places where people should read about vault.

docsite/rst/faq.rst

@@ -251,6 +251,13 @@ How do I submit a change to the documentation?
 
 Great question!  Documentation for Ansible is kept in the main project git repository, and complete instructions for contributing can be found in the docs README `viewable on GitHub <https://github.com/ansible/ansible/tree/devel/docsite/latest#readme>`_.  Thanks!
 
+.. _keep_secret_data:
+
+How do I keep secret data in my playbook?
++++++++++++++++++++++++++++++++++++++++++
+
+If you would like to keep secret data in your Ansible content and still share it publically or keep things in source control, see :doc:`playbooks_vault`.
+
 .. _i_dont_see_my_question:
 
 I don't see my question here

docsite/rst/intro_configuration.rst

@@ -584,7 +584,7 @@ Accelerate Mode Settings
 ------------------------
 
 Under the [accelerate] header, the following settings are tunable for :doc:`playbooks_acceleration`.  Acceleration is 
-a useful performance feature to use if you cannot enable :ref:`ssh_pipelining` in your environment, but is probably
+a useful performance feature to use if you cannot enable :ref:`pipelining` in your environment, but is probably
 not needed if you can.
 
 .. _accelerate_port:

docsite/rst/playbooks_acceleration.rst

@@ -5,7 +5,7 @@ Accelerated Mode
 
 .. note:
 
-   Are you running Ansible 1.5 or later?  If so, you may not need accelerate mode due to a new feature called "SSH pipelining" and should read the :doc:`pipelining` section of the documentation.
+   Are you running Ansible 1.5 or later?  If so, you may not need accelerate mode due to a new feature called "SSH pipelining" and should read the :ref:`pipelining` section of the documentation.
 
    For users on 1.5 and later, accelerate mode only makes sense if you are (A) are managing from an Enterprise Linux 6 or earlier host
    and still are on paramiko, or (B) can't enable TTYs with sudo as described in the pipelining docs.

docsite/rst/playbooks_lookups.rst

@@ -29,9 +29,16 @@ Contents can be read off the filesystem as follows::
 The Password Lookup
 ```````````````````
 
-``password`` generates a random plaintext password and store it in
-a file at a given filepath.  Support for crypted save modes (as with vars_prompt) is pending.  If the
-file exists previously, it will retrieve its contents, behaving just like with_file. Usage of variables like "{{ inventory_hostname }}" in the filepath can be used to set
+.. note::
+
+    A great alternative to the password lookup plugin, if you don't need to generate random passwords on a per-host basis, would be to use :doc:`playbooks_vault`.  Read the documentation there and consider using it first, it will be more desirable for most applications.
+
+``password`` generates a random plaintext password and stores it in
+a file at a given filepath.  
+
+(Docs about crypted save modes are pending)
+ 
+If the file exists previously, it will retrieve its contents, behaving just like with_file. Usage of variables like "{{ inventory_hostname }}" in the filepath can be used to set
 up random passwords per host (what simplifies password management in 'host_vars' variables).
 
 Generated passwords contain a random mix of upper and lowercase ASCII letters, the

docsite/rst/playbooks_special_topics.rst

@@ -16,4 +16,4 @@ and adopt these only if they seem relevant or useful to your environment.
    playbooks_lookups
    playbooks_prompts
    playbooks_tags
-
+   playbooks_vault