elaborate on a couple of sections

1 files changed, 28 insertions, 13 deletions

diff --git a/docsite/rst/guide_vagrant.rst b/docsite/rst/guide_vagrant.rst
index 11c9872adf..dc861b9153 100644
--- a/docsite/rst/guide_vagrant.rst
+++ b/docsite/rst/guide_vagrant.rst
@@ -19,13 +19,17 @@ This guide will describe how to use Vagrant and Ansible together.
 If you're not familar with Vagrant, you should visit `the documentation
 <http://docs.vagrantup.com/v2/>`_.
 
+This guide assumes that you already have Ansible installed and working.
+Running from a Git checkout is fine. Follow the :doc:`intro_installation`
+guide for more information.
+
 .. _vagrant_setup:
 
 Vagrant Setup
 `````````````
 
-The first step once you've installed Vagrant is to create a Vagrantfile and
-customize it to suit your needs. This is covered in detail in the Vagrant
+The first step once you've installed Vagrant is to create a ``Vagrantfile``
+and customize it to suit your needs. This is covered in detail in the Vagrant
 documentation, but here is a quick example:
 
 .. code-block:: bash
@@ -55,8 +59,8 @@ example that includes a section to use the Ansible provisioner:
     end
 
 The Vagrantfile has a lot of options, but these are the most important ones.
-Notice the "config.vm.provision" section that refers to an Ansible playbook
-called "playbook.yml" in the same directory as the Vagrantfile. Vagrant runs
+Notice the ``config.vm.provision`` section that refers to an Ansible playbook
+called ``playbook.yml`` in the same directory as the Vagrantfile. Vagrant runs
 the provisioner once the virtual machine has booted and is ready for SSH
 access.
 
@@ -66,24 +70,35 @@ access.
 
 This will start the VM and run the provisioning playbook.
 
-There are a lot of Ansible options you can configure in your Vagrantfile.
+There are a lot of Ansible options you can configure in your Vagrantfile. Some
+particularly useful options are ``ansible.extra_vars``, ``ansible.sudo`` and
+``ansible.sudo_user``, and ``ansible.host_key_checking`` which you can disable
+to avoid SSH connection problems to new virtual machines.
+
 Visit the `Ansible Provisioner documentation
 <http://docs.vagrantup.com/v2/provisioning/ansible.html>`_ for more
 information.
 
+To re-run a playbook on an existing VM, just run:
+
+.. code-block:: bash
+
+    $ vagrant provision
+
+This will re-run the playbook.
+
 .. _running_ansible:
 
 Running Ansible Manually
 ````````````````````````
 
-You can re-run the Ansible playbook for your Vagrant machine by running
-"vagrant provision", but sometimes you may want to run Ansible manually
-against the machines. This is pretty easy to do.
+Sometimes you may want to run Ansible manually against the machines. This is
+pretty easy to do.
 
 Vagrant automatically creates an inventory file for each Vagrant machine in
-the same directory called "vagrant_ansible_inventory_machinename". It
+the same directory called ``vagrant_ansible_inventory_machinename``. It
 configures the inventory file according to the SSH tunnel that Vagrant
-automatically creates, and executes "ansible-playbook" with the correct
+automatically creates, and executes ``ansible-playbook`` with the correct
 username and SSH key options to allow access. A typical automatically-created
 inventory file may look something like this:
 
@@ -94,9 +109,9 @@ inventory file may look something like this:
     machine ansible_ssh_host=127.0.0.1 ansible_ssh_port=2222
 
 If you want to run Ansible manually, you will want to make sure to pass
-"ansible" or "ansible-playbook" the correct arguments for the username
-(usually "vagrant") and the SSH key (usually
-"~/.vagrant.d/insecure_private_key"), and the autogenerated inventory file.
+``ansible`` or ``ansible-playbook`` commands the correct arguments for the
+username (usually ``vagrant``) and the SSH key (usually
+``~/.vagrant.d/insecure_private_key``), and the autogenerated inventory file.
 
 Here is an example: