introduce flag to manage the docroot

manage_docroot defaults to `true` to retain backwards compatibility.
This flag is  useful if the docroot is created by other, conflicting
means such as vcsrepo.

README.md

@@ -827,6 +827,10 @@ Sets individual user access to the docroot directory. Defaults to 'root'.
 
 Sets access permissions of the docroot directory. Defaults to 'undef'.
 
+#####`manage_docroot`
+
+Whether to manage to docroot directory at all. Defaults to 'true'.
+
 #####`error_log`
 
 Specifies whether `*_error.log` directives should be configured. Defaults to 'true'.

manifests/vhost.pp

@@ -77,6 +77,7 @@
 #
 define apache::vhost(
     $docroot,
+    $manage_docroot              = true,
     $virtual_docroot             = false,
     $port                        = undef,
     $ip                          = undef,
@@ -261,7 +262,7 @@
 
   # This ensures that the docroot exists
   # But enables it to be specified across multiple vhost resources
-  if ! defined(File[$docroot]) {
+  if ! defined(File[$docroot]) and $manage_docroot {
     file { $docroot:
       ensure  => directory,
       owner   => $docroot_owner,

spec/defines/vhost_spec.rb

@@ -1166,6 +1166,15 @@
         end
       end
 
+      describe 'when docroot is *not* managed' do
+        let :params do default_params.merge({
+          :manage_docroot=> false,
+        }) end
+        it 'should not contain docroot ' do
+          is_expected.not_to contain_file(params[:docroot])
+        end
+      end
+
       describe 'when wsgi_daemon_process and wsgi_daemon_process_options are specified' do
         let :params do default_params.merge({
           :wsgi_daemon_process         => 'example.org',