Merge pull request #10570 from chef/resource_docs

Signed-off-by: Tim Smith <tsmith@chef.io>

6 files changed, 247 insertions, 3 deletions

diff --git a/lib/chef/resource/scm/_scm.rb b/lib/chef/resource/scm/_scm.rb
index c939246ba1..573d8b9b94 100644
--- a/lib/chef/resource/scm/_scm.rb
+++ b/lib/chef/resource/scm/_scm.rb
@@ -33,7 +33,8 @@ property :revision, String,
   default: "HEAD"
 
 property :user, [String, Integer],
-  description: "The system user that will own the checked-out code."
+  description: "The system user that will own the checked-out code.",
+  default_description: "`HOME` environment variable of the user running #{ChefUtils::Dist::Infra::CLIENT}"
 
 property :group, [String, Integer],
   description: "The system group that will own the checked-out code."
diff --git a/lib/chef/resource/scm/git.rb b/lib/chef/resource/scm/git.rb
index b8c8f06347..53f1a1f44a 100644
--- a/lib/chef/resource/scm/git.rb
+++ b/lib/chef/resource/scm/git.rb
@@ -28,6 +28,87 @@ class Chef
       provides :git
 
       description "Use the **git** resource to manage source control resources that exist in a git repository. git version 1.6.5 (or higher) is required to use all of the functionality in the git resource."
+      examples <<~DOC
+      **Use the git mirror**
+
+      ```ruby
+      git '/opt/mysources/couch' do
+        repository 'git://git.apache.org/couchdb.git'
+        revision 'master'
+        action :sync
+      end
+      ```
+
+      **Use different branches**
+
+      To use different branches, depending on the environment of the node:
+
+      ```ruby
+      branch_name = if node.chef_environment == 'QA'
+                      'staging'
+                    else
+                      'master'
+                    end
+
+      git '/home/user/deployment' do
+         repository 'git@github.com:gitsite/deployment.git'
+         revision branch_name
+         action :sync
+         user 'user'
+         group 'test'
+      end
+      ```
+
+      Where the `branch_name` variable is set to staging or master, depending on the environment of the node. Once this is determined, the `branch_name` variable is used to set the revision for the repository. If the git status command is used after running the example above, it will return the branch name as `deploy`, as this is the default value. Run Chef Infra Client in debug mode to verify that the correct branches are being checked out:
+
+      ```
+      sudo chef-client -l debug
+      ```
+
+      **Install an application from git using bash**
+
+      The following example shows how Bash can be used to install a plug-in for rbenv named ruby-build, which is located in git version source control. First, the application is synchronized, and then Bash changes its working directory to the location in which ruby-build is located, and then runs a command.
+
+      ```ruby
+      git "#{Chef::Config[:file_cache_path]}/ruby-build" do
+        repository 'git://github.com/sstephenson/ruby-build.git'
+        revision 'master'
+        action :sync
+      end
+
+      bash 'install_ruby_build' do
+        cwd "#{Chef::Config[:file_cache_path]}/ruby-build"
+        user 'rbenv'
+        group 'rbenv'
+        code <<-EOH
+          ./install.sh
+          EOH
+        environment 'PREFIX' => '/usr/local'
+      end
+      ```
+
+      **Notify a resource post-checkout**
+
+      ```ruby
+      git "#{Chef::Config[:file_cache_path]}/libvpx" do
+        repository node[:libvpx][:git_repository]
+        revision node[:libvpx][:git_revision]
+        action :sync
+        notifies :run, 'bash[compile_libvpx]', :immediately
+      end
+      ```
+
+      **Pass in environment variables**
+
+      ```ruby
+      git '/opt/mysources/couch' do
+        repository 'git://git.apache.org/couchdb.git'
+        revision 'master'
+        environment 'VAR' => 'whatever'
+        action :sync
+      end
+      ```
+      DOC
 
       property :additional_remotes, Hash,
         description: "A Hash of additional remotes that are added to the git repository configuration.",
@@ -41,7 +122,7 @@ class Chef
         default: false
 
       property :enable_checkout, [TrueClass, FalseClass],
-        description: "Check out a repo from master. Set to false when using the checkout_branch attribute to prevent the git resource from attempting to check out master from master.",
+        description: "Check out a repo from master. Set to `false` when using the `checkout_branch` attribute to prevent the git resource from attempting to check out `master` from `master`.",
         default: true
 
       property :remote, String,
diff --git a/lib/chef/resource/scm/subversion.rb b/lib/chef/resource/scm/subversion.rb
index f5637b04ad..8399225fdf 100644
--- a/lib/chef/resource/scm/subversion.rb
+++ b/lib/chef/resource/scm/subversion.rb
@@ -29,6 +29,18 @@ class Chef
       provides :subversion
 
       description "Use the **subversion** resource to manage source control resources that exist in a Subversion repository."
+      examples <<~DOC
+      **Get the latest version of an application**
+
+      ```ruby
+      subversion 'CouchDB Edge' do
+        repository 'http://svn.apache.org/repos/asf/couchdb/trunk'
+        revision 'HEAD'
+        destination '/opt/mysources/couch'
+        action :sync
+      end
+      ```
+      DOC
 
       allowed_actions :force_export
 
diff --git a/lib/chef/resource/systemd_unit.rb b/lib/chef/resource/systemd_unit.rb
index fc9aa4d40f..b028214441 100644
--- a/lib/chef/resource/systemd_unit.rb
+++ b/lib/chef/resource/systemd_unit.rb
@@ -29,6 +29,47 @@ class Chef
 
       description "Use the **systemd_unit** resource to create, manage, and run [systemd units](https://www.freedesktop.org/software/systemd/man/systemd.html#Concepts)."
       introduced "12.11"
+      examples <<~DOC
+      **Create systemd service unit file from a Hash**
+
+      ```ruby
+      systemd_unit 'etcd.service' do
+        content({Unit: {
+                  Description: 'Etcd',
+                  Documentation: ['https://coreos.com/etcd', 'man:etcd(1)'],
+                  After: 'network.target',
+                },
+                Service: {
+                  Type: 'notify',
+                  ExecStart: '/usr/local/etcd',
+                  Restart: 'always',
+                },
+                Install: {
+                  WantedBy: 'multi-user.target',
+                }})
+        action [:create, :enable]
+      end
+      ```
+
+      **Create systemd service unit file from a String**
+
+      ```ruby
+      systemd_unit 'sysstat-collect.timer' do
+        content <<~EOU
+        [Unit]
+        Description=Run system activity accounting tool every 10 minutes
+
+        [Timer]
+        OnCalendar=*:00/10
+
+        [Install]
+        WantedBy=sysstat.service
+        EOU
+
+        action [:create, :enable]
+      end
+      ```
+      DOC
 
       default_action :nothing
       allowed_actions :create, :delete,
diff --git a/lib/chef/resource/windows_service.rb b/lib/chef/resource/windows_service.rb
index 0fa007497b..5920f61011 100644
--- a/lib/chef/resource/windows_service.rb
+++ b/lib/chef/resource/windows_service.rb
@@ -39,6 +39,114 @@ class Chef
 
       description "Use the **windows_service** resource to create, delete, or manage a service on the Microsoft Windows platform."
       introduced "12.0"
+      examples <<~DOC
+      **Starting Services**
+
+      Start a service with a `manual` startup type:
+
+      ```ruby
+      windows_service 'BITS' do
+        action :configure_startup
+        startup_type :manual
+      end
+      ```
+
+      **Creating Services**
+
+      Create a service named chef-client:
+
+      ```ruby
+      windows_service 'chef-client' do
+        action :create
+        binary_path_name "C:\\opscode\\chef\\bin"
+      end
+      ```
+
+      Create a service with `service_name` and `display_name`:
+
+      ```ruby
+      windows_service 'Setup chef-client as a service' do
+        action :create
+        display_name 'CHEF-CLIENT'
+        service_name 'chef-client'
+        binary_path_name "C:\\opscode\\chef\\bin"
+      end
+      ```
+
+      Create a service with the `manual` startup type:
+
+      ```ruby
+      windows_service 'chef-client' do
+        action :create
+        binary_path_name "C:\\opscode\\chef\\bin"
+        startup_type :manual
+      end
+      ```
+
+      Create a service with the `disabled` startup type:
+
+      ```ruby
+      windows_service 'chef-client' do
+        action :create
+        binary_path_name "C:\\opscode\\chef\\bin"
+        startup_type :disabled
+      end
+      ```
+
+      Create a service with the `automatic` startup type and delayed start enabled:
+
+      ```ruby
+      windows_service 'chef-client' do
+        action :create
+        binary_path_name "C:\\opscode\\chef\\bin"
+        startup_type :automatic
+        delayed_start true
+      end
+      ```
+
+      Create a service with a description:
+
+      ```ruby
+      windows_service 'chef-client' do
+        action :create
+        binary_path_name "C:\\opscode\\chef\\bin"
+        startup_type :automatic
+        description "Chef client as service"
+      end
+      ```
+
+      **Deleting Services**
+
+      Delete a service named chef-client:
+
+      ```ruby
+      windows_service 'chef-client' do
+        action :delete
+      end
+      ```
+
+      Delete a service with the `service_name` property:
+
+      ```ruby
+      windows_service 'Delete chef client' do
+        action :delete
+        service_name 'chef-client'
+      end
+      ```
+
+      **Configuring Services**
+
+      Change an existing service from automatic to manual startup:
+
+      ```ruby
+      windows_service 'chef-client' do
+        action :configure
+        binary_path_name "C:\\opscode\\chef\\bin"
+        startup_type :manual
+      end
+      ```
+      DOC
+
 
       allowed_actions :configure_startup, :create, :delete, :configure
 
diff --git a/lib/chef/resource/windows_task.rb b/lib/chef/resource/windows_task.rb
index cc2c80d4c6..29bade29ce 100644
--- a/lib/chef/resource/windows_task.rb
+++ b/lib/chef/resource/windows_task.rb
@@ -75,7 +75,7 @@ class Chef
         command 'chef-client'
         run_level :highest
         frequency :once
-        start_time "16:10"
+        start_time '16:10'
       end
       ```
 
@@ -115,6 +115,7 @@ class Chef
       ```
 
       **Create a scheduled task to run when computer is idle with idle duration 20 min**:
+
       ```ruby
       windows_task 'chef-client' do
         command 'chef-client'