provisioners/ansible: improve inventory docs

Related to a question asked in the mailing list:
https://groups.google.com/forum/#!topic/vagrant-up/OwkR04u4MA4

[ci skip]

website/docs/source/v2/provisioning/ansible.html.md

@@ -33,30 +33,30 @@ a single page of documentation.
 ## Inventory File
 
 When using Ansible, it needs to know on which machines a given playbook should run. It does
-this by way of an [inventory](http://docs.ansible.com/intro_inventory.html) file which lists those machines. In the context of Vagrant,
+this by way of an [inventory](http://docs.ansible.com/intro_inventory.html) file which lists those machines.
-there are two ways to approach working with inventory files.
+In the context of Vagrant, there are two ways to approach working with inventory files.
+
+### Auto-Generated Inventory
 
 The first and simplest option is to not provide one to Vagrant at all. Vagrant will generate an
 inventory file encompassing all of the virtual machines it manages, and use it for provisioning
 machines. The generated inventory file is stored as part of your local Vagrant environment in `.vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory`.
 
-The `ansible.groups` option can be used to pass a hash of group
+**Groups of Hosts**
-names and group members to be included in the generated inventory file. Group variables
+
-are intentionally not supported, as this practice is not recommended.
+The `ansible.groups` option can be used to pass a hash of group names and group members to be included in the generated inventory file.
-For example:
+
+With this configuration example:
 
 ```
 ansible.groups = {
   "group1" => ["machine1"],
-  "group2" => ["machine2", "machine3"],
+  "group2" => ["machine2"],
-  "all_groups:children" => ["group1", "group2", "group3"]
+  "all_groups:children" => ["group1", "group2"]
 }
 ```
 
-Note that unmanaged machines and undefined groups are not added to the inventory.
+Vagrant would generate an inventory file that might look like:
-For example, `group3` in the above example would not be added to the inventory file.
-
-A generated inventory might look like:
 
 ```
 # Generated by Vagrant
@@ -75,6 +75,24 @@ group1
 group2
 ```
 
+**Notes**
+
+ * The generation of group variables blocks (e.g. `[group1:vars]`) are intentionally not supported, as it is [not recommended to store group variables in the main inventory file](http://docs.ansible.com/intro_inventory.html#splitting-out-host-and-group-specific-data). A good practice is to store these group (or host) variables in `YAML` files stored in `group_vars/` or `host_vars/` directories in the playbook (or inventory) directory.
+ * Unmanaged machines and undefined groups are not added to the inventory, to avoid useless Ansible errors (e.g. *unreachable host* or *undefined child group*)
+
+For example, `machine3`, `group3` and `group1:vars` in the example below would not be added to the generated inventory file:
+
+```
+ansible.groups = {
+  "group1" => ["machine1"],
+  "group2" => ["machine2", "machine3"],
+  "all_groups:children" => ["group1", "group2", "group3"],
+  "group1:vars" => { "variable1" => 9, "variable2" => "example" }
+}
+```
+
+### Static Inventory
+
 The second option is for situations where you'd like to have more control over the inventory management.
 With the `ansible.inventory_path` option, you can reference a specific inventory resource (e.g. a static inventory file, a [dynamic inventory script](http://docs.ansible.com/intro_dynamic_inventory.html) or even [multiple inventories stored in the same directory](http://docs.ansible.com/intro_dynamic_inventory.html#using-multiple-inventory-sources)). Vagrant will then use this inventory information instead of generating it.
 
@@ -90,8 +108,10 @@ Where the above IP address is one set in your Vagrantfile:
 config.vm.network :private_network, ip: "192.168.111.222"
 ```
 
-Note that machine names in `Vagrantfile` and `ansible.inventory_path` file should correspond,
+**Notes:**
-unless you use `ansible.limit` option to reference the correct machines.
+
+ * The machine names in `Vagrantfile` and `ansible.inventory_path` files should correspond, unless you use `ansible.limit` option to reference the correct machines.
+ * The SSH host addresses (and ports) must obviously be specified twice, in `Vagrantfile` and `ansible.inventory_path` files.
 
 ## Playbook