Merge pull request #8868 from chef/examples

Add more resource examples to the codebase

12 files changed, 223 insertions, 21 deletions

diff --git a/lib/chef/resource/apt_repository.rb b/lib/chef/resource/apt_repository.rb
index dff8139647..213acc166b 100644
--- a/lib/chef/resource/apt_repository.rb
+++ b/lib/chef/resource/apt_repository.rb
@@ -1,6 +1,6 @@
 #
 # Author:: Thom May (<thom@chef.io>)
-# Copyright:: 2016-2017, Chef Software, Inc.
+# Copyright:: 2016-2019, Chef Software, Inc.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -35,8 +35,9 @@ class Chef
           components ['nginx']
         end
         ```
-         Enable Ubuntu multiverse repositories
-         ```ruby
+
+        Enable Ubuntu multiverse repositories
+        ```ruby
         apt_repository 'security-ubuntu-multiverse' do
           uri          'http://security.ubuntu.com/ubuntu'
           distribution 'trusty-security'
@@ -44,14 +45,16 @@ class Chef
           deb_src      true
         end
         ```
-         Add the Nginx PPA, autodetect the key and repository url
-         ```ruby
+
+        Add the Nginx PPA, autodetect the key and repository url
+        ```ruby
         apt_repository 'nginx-php' do
           uri          'ppa:nginx/stable'
         end
         ```
-         Add the JuJu PPA, grab the key from the keyserver, and add source repo
-         ```ruby
+
+        Add the JuJu PPA, grab the key from the keyserver, and add source repo
+        ```ruby
         apt_repository 'juju' do
           uri 'http://ppa.launchpad.net/juju/stable/ubuntu'
           components ['main']
@@ -62,8 +65,9 @@ class Chef
           deb_src true
         end
         ```
-         Add repository that requires multiple keys to authenticate packages
-         ```ruby
+
+        Add repository that requires multiple keys to authenticate packages
+        ```ruby
         apt_repository 'rundeck' do
           uri 'https://dl.bintray.com/rundeck/rundeck-deb'
           distribution '/'
@@ -72,8 +76,9 @@ class Chef
           action :add
         end
         ```
-         Add the Cloudera Repo of CDH4 packages for Ubuntu 12.04 on AMD64
-         ```ruby
+
+        Add the Cloudera Repo of CDH4 packages for Ubuntu 12.04 on AMD64
+        ```ruby
         apt_repository 'cloudera' do
           uri          'http://archive.cloudera.com/cdh4/ubuntu/precise/amd64/cdh'
           arch         'amd64'
@@ -82,8 +87,9 @@ class Chef
           key          'http://archive.cloudera.com/debian/archive.key'
         end
         ```
-         Remove a repository from the list
-         ```ruby
+
+        Remove a repository from the list
+        ```ruby
         apt_repository 'zenoss' do
           action :remove
         end
diff --git a/lib/chef/resource/apt_update.rb b/lib/chef/resource/apt_update.rb
index e11d35664f..330f5b6071 100644
--- a/lib/chef/resource/apt_update.rb
+++ b/lib/chef/resource/apt_update.rb
@@ -1,6 +1,6 @@
 #
 # Author:: Thom May (<thom@chef.io>)
-# Copyright:: Copyright (c) 2016-2017, Chef Software Inc.
+# Copyright:: Copyright (c) 2016-2019, Chef Software Inc.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -26,6 +26,20 @@ class Chef
 
       description "Use the apt_update resource to manage APT repository updates on Debian and Ubuntu platforms."
       introduced "12.7"
+      examples <<~DOC
+        Update the Apt repository at a specified interval
+        ```ruby
+        apt_update 'all platforms' do
+        frequency 86400
+        action :periodic
+        end
+        ```
+
+        Update the Apt repository at the start of a Chef Infra Client run
+        ```ruby
+        apt_update 'update'
+        ```
+      DOC
 
       # allow bare apt_update with no name
       property :name, String, default: ""
diff --git a/lib/chef/resource/archive_file.rb b/lib/chef/resource/archive_file.rb
index 958da23a1b..dd208fb60f 100644
--- a/lib/chef/resource/archive_file.rb
+++ b/lib/chef/resource/archive_file.rb
@@ -1,5 +1,5 @@
 #
-# Copyright:: Copyright 2017-2018, Chef Software Inc.
+# Copyright:: Copyright 2017-2019, Chef Software Inc.
 # Author:: Jamie Winsor (<jamie@vialstudios.com>)
 # Author:: Tim Smith (<tsmith@chef.io>)
 #
@@ -30,6 +30,15 @@ class Chef
 
       introduced "15.0"
       description "Use the archive_file resource to extract archive files to disk. This resource uses the libarchive library to extract multiple archive formats including tar, gzip, bzip, and zip formats."
+      examples <<~DOC
+        Extract a zip file to a specified directory
+        ```ruby
+        archive_file 'Precompiled.zip' do
+          path '/tmp/Precompiled.zip'
+          destination '/srv/files'
+        end
+        ```
+      DOC
 
       property :path, String,
         name_property: true,
diff --git a/lib/chef/resource/build_essential.rb b/lib/chef/resource/build_essential.rb
index b38ec6b24a..105173bc88 100644
--- a/lib/chef/resource/build_essential.rb
+++ b/lib/chef/resource/build_essential.rb
@@ -1,5 +1,5 @@
 #
-# Copyright:: 2008-2018, Chef Software, Inc.
+# Copyright:: 2008-2019, Chef Software, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -24,6 +24,19 @@ class Chef
 
       description "Use the build_essential resource to install packages required for compiling C software from source."
       introduced "14.0"
+      examples <<~DOC
+        Install compilation packages
+        ```ruby
+        build_essential
+        ```
+
+        Install compilation packages during the compilation phase
+        ```ruby
+        build_essential 'Install compilation tools' do
+          compile_time true
+        end
+        ```
+      DOC
 
       # this allows us to use build_essential without setting a name
       property :name, String, default: ""
diff --git a/lib/chef/resource/chocolatey_config.rb b/lib/chef/resource/chocolatey_config.rb
index 2be4b7be0a..216dc85fc9 100644
--- a/lib/chef/resource/chocolatey_config.rb
+++ b/lib/chef/resource/chocolatey_config.rb
@@ -1,5 +1,5 @@
 #
-# Copyright:: 2018, Chef Software, Inc.
+# Copyright:: 2018-2019, Chef Software, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -21,6 +21,22 @@ class Chef
 
       description "Use the chocolatey_config resource to add or remove Chocolatey configuration keys."
       introduced "14.3"
+      examples <<~DOC
+        Set the Chocolatey cacheLocation config
+        ```ruby
+        chocolatey_config 'Set cacheLocation config' do
+          config_key 'cacheLocation'
+          value 'C:\temp\choco'
+        end
+        ```
+
+        Unset a Chocolatey config
+        ```ruby
+        chocolatey_config 'BogusConfig' do
+          action :unset
+        end
+        ```
+      DOC
 
       property :config_key, String, name_property: true,
                description: "An optional property to set the config key name if it differs from the resource block's name."
diff --git a/lib/chef/resource/chocolatey_feature.rb b/lib/chef/resource/chocolatey_feature.rb
index 0fa053935d..37ca9c0228 100644
--- a/lib/chef/resource/chocolatey_feature.rb
+++ b/lib/chef/resource/chocolatey_feature.rb
@@ -21,6 +21,21 @@ class Chef
 
       description "Use the chocolatey_feature resource to enable and disable Chocolatey features."
       introduced "15.1"
+      examples <<~DOC
+        Enable the checksumFiles Chocolatey feature
+        ```ruby
+        chocolatey_feature 'checksumFiles' do
+          action :enable
+        end
+        ```
+
+        Disable the checksumFiles Chocolatey feature
+        ```ruby
+        chocolatey_feature 'checksumFiles' do
+          action :disable
+        end
+        ```
+      DOC
 
       property :feature_name, String, name_property: true,
                description: "The name of the Chocolatey feature to enable or disable."
diff --git a/lib/chef/resource/chocolatey_package.rb b/lib/chef/resource/chocolatey_package.rb
index 6feae23686..1a0a82ebd2 100644
--- a/lib/chef/resource/chocolatey_package.rb
+++ b/lib/chef/resource/chocolatey_package.rb
@@ -26,6 +26,22 @@ class Chef
 
       description "Use the chocolatey_package resource to manage packages using Chocolatey on the Microsoft Windows platform."
       introduced "12.7"
+      examples <<~DOC
+        Install a Chocolatey package
+        ```ruby
+        chocolatey_package 'name of package' do
+          action :install
+        end
+        ```
+
+        Install a package with options with Chocolatey's ``--checksum`` option
+        ```ruby
+        chocolatey_package 'name of package' do
+          options '--checksum 1234567890'
+          action :install
+        end
+        ```
+      DOC
 
       allowed_actions :install, :upgrade, :remove, :purge, :reconfig
 
diff --git a/lib/chef/resource/chocolatey_source.rb b/lib/chef/resource/chocolatey_source.rb
index 9f57e0dbdc..f002d7d28b 100644
--- a/lib/chef/resource/chocolatey_source.rb
+++ b/lib/chef/resource/chocolatey_source.rb
@@ -1,5 +1,5 @@
 #
-# Copyright:: 2018, Chef Software, Inc.
+# Copyright:: 2018-2019, Chef Software, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -21,6 +21,22 @@ class Chef
 
       description "Use the chocolatey_source resource to add, remove, enable, or disable Chocolatey sources."
       introduced "14.3"
+      examples <<~DOC
+        Add a Chocolatey source
+        ```ruby
+        chocolatey_source 'MySource' do
+          source 'http://example.com/something'
+          action :add
+        end
+        ```
+
+        Remove a Chocolatey source
+        ```ruby
+        chocolatey_source 'MySource' do
+          action :remove
+        end
+        ```
+      DOC
 
       property :source_name, String, name_property: true,
                description: "An optional property to set the source name if it differs from the resource block's name."
diff --git a/lib/chef/resource/cron_access.rb b/lib/chef/resource/cron_access.rb
index 6c0272b667..3ee371e9fa 100644
--- a/lib/chef/resource/cron_access.rb
+++ b/lib/chef/resource/cron_access.rb
@@ -3,7 +3,7 @@
 # Author:: Tim Smith <tsmith@chef.io>
 #
 # Copyright:: 2014-2018, Sander Botman
-# Copyright:: 2018, Chef Software, Inc.
+# Copyright:: 2018-2019, Chef Software, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -28,6 +28,27 @@ class Chef
 
       introduced "14.4"
       description "Use the cron_access resource to manage the /etc/cron.allow and /etc/cron.deny files."
+      examples <<~DOC
+        Add the mike user to cron.allow
+        ```ruby
+        cron_access 'mike'
+        ```
+
+        Add the mike user to cron.deny
+        ```ruby
+        cron_access 'mike' do
+          action :deny
+        end
+        ```
+
+        Specify the username with the user property
+        ```ruby
+        cron_access 'Deny the tomcat access to cron for security purposes' do
+          user 'jenkins'
+          action :deny
+        end
+        ```
+      DOC
 
       property :user, String,
         description: "An optional property to set the user name if it differs from the resource block's name.",
diff --git a/lib/chef/resource/cron_d.rb b/lib/chef/resource/cron_d.rb
index c9bc8fcb1d..ca3b91a4b2 100644
--- a/lib/chef/resource/cron_d.rb
+++ b/lib/chef/resource/cron_d.rb
@@ -1,5 +1,5 @@
 #
-# Copyright:: 2008-2018, Chef Software, Inc.
+# Copyright:: 2008-2019, Chef Software, Inc.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -26,6 +26,51 @@ class Chef
 
       introduced "14.4"
       description "Use the cron_d resource to manage cron definitions in /etc/cron.d. This is similar to the 'cron' resource, but it does not use the monolithic /etc/crontab file."
+      examples <<~DOC
+        To run a program on the fifth hour of the day
+        ```ruby
+        cron_d 'noop' do
+          hour '5'
+          minute '0'
+          command '/bin/true'
+        end
+        ```
+
+        To run an entry if a folder exists
+        ```ruby
+        cron_d 'ganglia_tomcat_thread_max' do
+          command "/usr/bin/gmetric
+            -n 'tomcat threads max'
+            -t uint32
+            -v '/usr/local/bin/tomcat-stat
+            --thread-max'"
+          only_if { ::File.exist?('/home/jboss') }
+        end
+        ```
+
+        To run an entry every Saturday, 8:00 AM
+        ```ruby
+        cron_d 'name_of_cron_entry' do
+          minute '0'
+          hour '8'
+          weekday '6'
+          mailto 'admin@example.com'
+          action :create
+        end
+        ```
+
+        To run an entry at 8:00 PM, every weekday (Monday through Friday), but only in November
+        ```ruby
+        cron_d 'name_of_cron_entry' do
+          minute '0'
+          hour '20'
+          day '*'
+          month '11'
+          weekday '1-5'
+          action :create
+        end
+        ```
+      DOC
 
       # validate a provided value is between two other provided values
       # we also allow * as a valid input
diff --git a/lib/chef/resource/dmg_package.rb b/lib/chef/resource/dmg_package.rb
index 403716cad7..869d7304b3 100644
--- a/lib/chef/resource/dmg_package.rb
+++ b/lib/chef/resource/dmg_package.rb
@@ -25,6 +25,34 @@ class Chef
 
       description "Use the dmg_package resource to install a dmg 'package'. The resource will retrieve the dmg file from a remote URL, mount it using OS X's hdidutil, copy the application (.app directory) to the specified destination (/Applications), and detach the image using hdiutil. The dmg file will be stored in the Chef::Config[:file_cache_path]."
       introduced "14.0"
+      examples <<~DOC
+        Install Google Chrome via the DMG package
+        ```ruby
+        dmg_package 'Google Chrome' do
+          dmg_name 'googlechrome'
+          source   'https://dl-ssl.google.com/chrome/mac/stable/GGRM/googlechrome.dmg'
+          checksum '7daa2dc5c46d9bfb14f1d7ff4b33884325e5e63e694810adc58f14795165c91a'
+          action   :install
+        end
+        ```
+
+        Install Virtualbox from the .mpkg
+        ```ruby
+        dmg_package 'Virtualbox' do
+          source 'http://dlc.sun.com.edgesuite.net/virtualbox/4.0.8/VirtualBox-4.0.8-71778-OSX.dmg'
+          type   'mpkg'
+        end
+        ```
+
+        Install pgAdmin and automatically accept the EULA
+        ```ruby
+        dmg_package 'pgAdmin3' do
+          source   'http://wwwmaster.postgresql.org/redir/198/h/pgadmin3/release/v1.12.3/osx/pgadmin3-1.12.3.dmg'
+          checksum '9435f79d5b52d0febeddfad392adf82db9df159196f496c1ab139a6957242ce9'
+          accept_eula true
+        end
+        ```
+      DOC
 
       property :app, String,
         description: "The name of the application as it appears in the /Volumes directory if it differs from the resource block's name.",
diff --git a/tasks/docs.rb b/tasks/docs.rb
index db89354517..8fa56e9e09 100755
--- a/tasks/docs.rb
+++ b/tasks/docs.rb
@@ -327,7 +327,10 @@ The <%= @name %> resource has the following properties:
 <% if @properties.empty? %>This resource does not have any properties.\n<% end -%>
 <%= boilerplate_content %>
 Examples
-==========================================
+=====================================================
+
+The following examples demonstrate various approaches for using resources in recipes:
+
 <%= @examples -%>
 }