Ansible: code cleanup and documentation update

Clean Up (code logic is kept unmodified):
* Remove repetition around `ansible.limit` option (merge conflict issue)
* Re-add missing comments from GH-1697 (merge conflict issue)
* Reorder instructions

Documentation for following changes:
* [GH-1697] add more options
* [GH-1979] extra verbosity option

plugins/provisioners/ansible/provisioner.rb

@@ -4,15 +4,13 @@ module VagrantPlugins
       def provision
         ssh = @machine.ssh_info
 
-        inventory_file_path = self.setup_inventory_file
+        # Connect with Vagrant user (unless --user or --private-key are overidden by 'raw_arguments')
         options = %W[--private-key=#{ssh[:private_key_path]} --user=#{ssh[:username]}]
 
         # Joker! Not (yet) supported arguments can be passed this way.
         options << "#{config.raw_arguments}" if config.raw_arguments
 
-        options << "--inventory-file=#{inventory_file_path}"
-        options << "--ask-sudo-pass" if config.ask_sudo_pass
-
+        # Append Provisioner options (higher precedence):
         if config.extra_vars
           extra_vars = config.extra_vars.map do |k,v|
             v = v.gsub('"', '\\"')
@@ -23,25 +21,13 @@ module VagrantPlugins
 
             "#{k}=#{v}"
           end
-
           options << "--extra-vars=\"#{extra_vars.join(" ")}\""
         end
-
-        if config.limit
-          if not config.limit.kind_of?(Array)
-            config.limit = [config.limit]
-          end
-          config.limit = config.limit.join(",")
-          options << "--limit=#{config.limit}"
-        end
-
+        options << "--inventory-file=#{self.setup_inventory_file}"
         options << "--sudo" if config.sudo
         options << "--sudo-user=#{config.sudo_user}" if config.sudo_user
-        if config.verbose
-          options << (config.verbose.to_s == "extra" ?  "-vvv" :  "--verbose")
-        end
-
-        # Append Provisioner options (higher precedence):
+        options << (config.verbose.to_s == "extra" ?  "-vvv" :  "--verbose") if config.verbose
+        options << "--ask-sudo-pass" if config.ask_sudo_pass
         options << "--tags=#{as_list_argument(config.tags)}" if config.tags
         options << "--skip-tags=#{as_list_argument(config.skip_tags)}" if config.skip_tags
         options << "--limit=#{as_list_argument(config.limit)}" if config.limit
@@ -70,6 +56,10 @@ module VagrantPlugins
         end
       end
 
+      protected
+
+      # Auto-generate "safe" inventory file based on Vagrantfile,
+      # unless inventory_path is explicitly provided
       def setup_inventory_file
         return config.inventory_path if config.inventory_path
 
@@ -86,8 +76,6 @@ module VagrantPlugins
         return generated_inventory_file.to_s
       end
 
-      protected
-
       def as_list_argument(v)
         v.kind_of?(Array) ? v.join(',') : v
       end

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

@@ -121,7 +121,11 @@ These variables take the highest precedence over any other variables.
 * `ansible.sudo_user` can be set to a string containing a username on the guest who should be used
 by the sudo command.
 * `ansible.ask_sudo_pass` can be set to `true` to require Ansible to prompt for a sudo password.
-* `ansible.limit` can be set to a string or an array of machines or groups from the inventory file
-to further narrow down which hosts are affected.
-* `ansible.verbose` can be set to `true` to increase Ansible's verbosity to obtain more detailed logging
-during playbook execution.
+* `ansible.limit` can be set to a string or an array of machines or groups from the inventory file to further narrow down which hosts are affected.
+* `ansible.verbose` can be set to `:extra` or `'extra'` to increase Ansible's verbosity to obtain full detailed logging (`-vvv`). Otherwise default verbosity level (`--verbose`) is applied.
+* `ansible.tags` can be set to a string or an array of tags. Only plays, roles and tasks tagged with these values will be executed.
+* `ansible.skip_tags` can be set to a string or an array of tags. Only plays, roles and tasks that *do not match* these values will be executed.
+* `ansible.start_at_task` can be set to a string corresponding to the task name where the playbook provision will start.
+* `ansible.raw_arguments` is an *unsafe wildcard* string that can be used to take advantage of `ansible-playbook` arguments that are not (yet) supported by this Vagrant provisioner plugin. This can be very useful when integrating with bleeding edge Ansible versions. Following precedence rules apply:
+  * Any supported options (described above) will override conflicting `raw_arguments` value (e.g. `--tags` or `--start-at-task`)
+  * Vagrant default user authentication can be overridden via `raw_arguments` (with custom values for `--user` and `--private-key`)