Merge pull request #10596 from chef/docs

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

11 files changed, 139 insertions, 20 deletions

diff --git a/cspell.json b/cspell.json
index 76e51788b9..b63cc0f898 100644
--- a/cspell.json
+++ b/cspell.json
@@ -16,7 +16,6 @@
   "words": [
     "abcz",
     "Abdulin",
-    "badssl",
     "ABORTIFHUNG",
     "ACCOUNTDISABLE",
     "activationkey",
@@ -111,6 +110,7 @@
     "backupfile",
     "BADKEY",
     "badpasswordattempts",
+    "badssl",
     "balasankarc",
     "Balatero",
     "barbaz",
@@ -418,7 +418,6 @@
     "Eachern",
     "EASTEUROPE",
     "EBUSY",
-    "escapepath",
     "eckey",
     "ecparam",
     "edir",
@@ -452,6 +451,7 @@
     "Erubis",
     "Eruby",
     "esac",
+    "escapepath",
     "ESRCH",
     "etag",
     "etags",
@@ -761,6 +761,7 @@
     "Juanje",
     "jugatsu",
     "julienhuon",
+    "jxvf",
     "katello",
     "Kauppila",
     "kaustubh",
@@ -1173,6 +1174,7 @@
     "PASSWORDNAME",
     "PATCHLEVEL",
     "pathed",
+    "PATHEXT",
     "PATHFINDING",
     "pathnames",
     "pbkdf",
@@ -1879,7 +1881,6 @@
     "Zanetti",
     "Zapp",
     "zeproc",
-    "PATHEXT",
     "ZEROEXEC",
     "ZEROINIT",
     "Zimmek",
diff --git a/lib/chef/resource/bash.rb b/lib/chef/resource/bash.rb
index bf59c87a9e..9ed6dc68d5 100644
--- a/lib/chef/resource/bash.rb
+++ b/lib/chef/resource/bash.rb
@@ -25,7 +25,125 @@ class Chef
 
       provides :bash
 
-      description "Use the **bash** resource to execute scripts using the Bash interpreter. This resource may also use any of the actions and properties that are available to the execute resource. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if and only_if to guard this resource for idempotence."
+      description "Use the **bash** resource to execute scripts using the Bash interpreter. This resource may also use any of the actions and properties that are available to the **execute** resource. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use `not_if` and `only_if` to guard this resource for idempotence."
+      examples <<~'DOC'
+      **Compile an application**
+
+      ```ruby
+      bash 'install_something' do
+        user 'root'
+        cwd '/tmp'
+        code <<-EOH
+          wget http://www.example.com/tarball.tar.gz
+          tar -zxf tarball.tar.gz
+          cd tarball
+          ./configure
+          make
+          make install
+        EOH
+      end
+      ```
+
+      **Install a file from a remote location**
+
+      The following is an example of how to install the foo123 module for Nginx. This module adds shell-style functionality to an Nginx configuration file and does the following:
+
+        - Declares three variables
+        - Gets the Nginx file from a remote location
+        - Installs the file using Bash to the path specified by the `src_filepath` variable
+
+      ```ruby
+      src_filename = "foo123-nginx-module-v#{node['nginx']['foo123']['version']}.tar.gz"
+      src_filepath = "#{Chef::Config['file_cache_path']}/#{src_filename}"
+      extract_path = "#{Chef::Config['file_cache_path']}/nginx_foo123_module/#{node['nginx']['foo123']['checksum']}"
+
+      remote_file 'src_filepath' do
+        source node['nginx']['foo123']['url']
+        checksum node['nginx']['foo123']['checksum']
+        owner 'root'
+        group 'root'
+        mode '0755'
+      end
+
+      bash 'extract_module' do
+        cwd ::File.dirname(src_filepath)
+        code <<-EOH
+          mkdir -p #{extract_path}
+          tar xzf #{src_filename} -C #{extract_path}
+          mv #{extract_path}/*/* #{extract_path}/
+        EOH
+        not_if { ::File.exist?(extract_path) }
+      end
+      ```
+
+      **Install an application from git**
+
+      ```ruby
+      git "#{Chef::Config[:file_cache_path]}/ruby-build" do
+        repository 'git://github.com/rbenv/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
+      ```
+
+      **Using Attributes in Bash Code**
+
+      The following recipe shows how an attributes file can be used to store certain settings. An attributes file is located in the `attributes/`` directory in the same cookbook as the recipe which calls the attributes file. In this example, the attributes file specifies certain settings for Python that are then used across all nodes against which this recipe will run.
+
+      Python packages have versions, installation directories, URLs, and checksum files. An attributes file that exists to support this type of recipe would include settings like the following:
+
+      ```ruby
+      default['python']['version'] = '2.7.1'
+
+      if python['install_method'] == 'package'
+        default['python']['prefix_dir'] = '/usr'
+      else
+        default['python']['prefix_dir'] = '/usr/local'
+      end
+
+      default['python']['url'] = 'http://www.python.org/ftp/python'
+      default['python']['checksum'] = '80e387...85fd61'
+      ```
+
+      and then the methods in the recipe may refer to these values. A recipe that is used to install Python will need to do the following:
+
+        - Identify each package to be installed (implied in this example, not shown)
+        - Define variables for the package `version` and the `install_path`
+        - Get the package from a remote location, but only if the package does not already exist on the target system
+        - Use the **bash** resource to install the package on the node, but only when the package is not already installed
+
+      ```ruby
+      version = node['python']['version']
+      install_path = "#{node['python']['prefix_dir']}/lib/python#{version.split(/(^\d+\.\d+)/)[1]}"
+
+      remote_file "#{Chef::Config[:file_cache_path]}/Python-#{version}.tar.bz2" do
+        source "#{node['python']['url']}/#{version}/Python-#{version}.tar.bz2"
+        checksum node['python']['checksum']
+        mode '0755'
+        not_if { ::File.exist?(install_path) }
+      end
+
+      bash 'build-and-install-python' do
+        cwd Chef::Config[:file_cache_path]
+        code <<-EOF
+          tar -jxvf Python-#{version}.tar.bz2
+          (cd Python-#{version} && ./configure #{configure_options})
+          (cd Python-#{version} && make && make install)
+        EOF
+        not_if { ::File.exist?(install_path) }
+      end
+      ```
+      DOC
 
       def initialize(name, run_context = nil)
         super
diff --git a/lib/chef/resource/batch.rb b/lib/chef/resource/batch.rb
index 4a9935a920..bbb5e73905 100644
--- a/lib/chef/resource/batch.rb
+++ b/lib/chef/resource/batch.rb
@@ -25,7 +25,7 @@ class Chef
 
       provides :batch
 
-      description "Use the **batch** resource to execute a batch script using the cmd.exe interpreter on Windows. The batch resource creates and executes a temporary file (similar to how the script resource behaves), rather than running the command inline. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if and only_if to guard this resource for idempotence."
+      description "Use the **batch** resource to execute a batch script using the cmd.exe interpreter on Windows. The batch resource creates and executes a temporary file (similar to how the script resource behaves), rather than running the command inline. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use `not_if` and `only_if` to guard this resource for idempotence."
 
       def initialize(*args)
         super
diff --git a/lib/chef/resource/csh.rb b/lib/chef/resource/csh.rb
index 6bfb4ddf8e..6f0c37d01e 100644
--- a/lib/chef/resource/csh.rb
+++ b/lib/chef/resource/csh.rb
@@ -27,9 +27,9 @@ class Chef
 
       description "Use the **csh** resource to execute scripts using the csh interpreter."\
                   " This resource may also use any of the actions and properties that are"\
-                  " available to the execute resource. Commands that are executed with this"\
+                  " available to the **execute** resource. Commands that are executed with this"\
                   " resource are (by their nature) not idempotent, as they are typically"\
-                  " unique to the environment in which they are run. Use not_if and only_if"\
+                  " unique to the environment in which they are run. Use `not_if` and `only_if`"\
                   " to guard this resource for idempotence."
 
       def initialize(name, run_context = nil)
diff --git a/lib/chef/resource/execute.rb b/lib/chef/resource/execute.rb
index db6b84dfda..7a561209fc 100644
--- a/lib/chef/resource/execute.rb
+++ b/lib/chef/resource/execute.rb
@@ -27,7 +27,7 @@ class Chef
 
       provides :execute, target_mode: true
 
-      description "Use the **execute** resource to execute a single command. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if and only_if to guard this resource for idempotence. Note: Use the **script** resource to execute a script using a specific interpreter (Ruby, Python, Perl, csh, or Bash)."
+      description "Use the **execute** resource to execute a single command. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use `not_if` and `only_if` to guard this resource for idempotence. Note: Use the **script** resource to execute a script using a specific interpreter (Ruby, Python, Perl, csh, or Bash)."
 
       examples <<~EXAMPLES
         **Run a command upon notification**:
diff --git a/lib/chef/resource/ksh.rb b/lib/chef/resource/ksh.rb
index 90f1a784c9..28d71970e7 100644
--- a/lib/chef/resource/ksh.rb
+++ b/lib/chef/resource/ksh.rb
@@ -27,10 +27,10 @@ class Chef
 
       description "Use the **ksh** resource to execute scripts using the Korn shell (ksh)"\
                   " interpreter. This resource may also use any of the actions and properties"\
-                  " that are available to the execute resource. Commands that are executed"\
+                  " that are available to the **execute** resource. Commands that are executed"\
                   " with this resource are (by their nature) not idempotent, as they are"\
-                  " typically unique to the environment in which they are run. Use not_if"\
-                  " and only_if to guard this resource for idempotence."
+                  " typically unique to the environment in which they are run. Use `not_if`"\
+                  " and `only_if` to guard this resource for idempotence."
       introduced "12.6"
 
       def initialize(name, run_context = nil)
diff --git a/lib/chef/resource/perl.rb b/lib/chef/resource/perl.rb
index 21f9755bc5..ac98c69a8c 100644
--- a/lib/chef/resource/perl.rb
+++ b/lib/chef/resource/perl.rb
@@ -32,9 +32,9 @@ class Chef
 
       description "Use the **perl** resource to execute scripts using the Perl interpreter."\
                   " This resource may also use any of the actions and properties that are"\
-                  " available to the execute resource. Commands that are executed with this"\
+                  " available to the **execute** resource. Commands that are executed with this"\
                   " resource are (by their nature) not idempotent, as they are typically"\
-                  " unique to the environment in which they are run. Use not_if and only_if"\
+                  " unique to the environment in which they are run. Use `not_if` and `only_if`"\
                   " to guard this resource for idempotence."
     end
   end
diff --git a/lib/chef/resource/python.rb b/lib/chef/resource/python.rb
index 6c2aeee4b8..0b36ca0bbd 100644
--- a/lib/chef/resource/python.rb
+++ b/lib/chef/resource/python.rb
@@ -31,9 +31,9 @@ class Chef
 
       description "Use the **python** resource to execute scripts using the Python interpreter."\
                   " This resource may also use any of the actions and properties that are available"\
-                  " to the execute resource. Commands that are executed with this resource are (by"\
+                  " to the **execute** resource. Commands that are executed with this resource are (by"\
                   " their nature) not idempotent, as they are typically unique to the environment in"\
-                  " which they are run. Use not_if and only_if to guard this resource for idempotence."
+                  " which they are run. Use `not_if` and `only_if` to guard this resource for idempotence."
     end
   end
 end
diff --git a/lib/chef/resource/ruby.rb b/lib/chef/resource/ruby.rb
index ba5aec103b..a9f3ae24fd 100644
--- a/lib/chef/resource/ruby.rb
+++ b/lib/chef/resource/ruby.rb
@@ -27,9 +27,9 @@ class Chef
 
       description "Use the **ruby** resource to execute scripts using the Ruby interpreter. This"\
                   " resource may also use any of the actions and properties that are available"\
-                  " to the execute resource. Commands that are executed with this resource are (by"\
+                  " to the **execute** resource. Commands that are executed with this resource are (by"\
                   " their nature) not idempotent, as they are typically unique to the environment"\
-                  " in which they are run. Use not_if and only_if to guard this resource for idempotence."
+                  " in which they are run. Use `not_if` and `only_if` to guard this resource for idempotence."
 
       def initialize(name, run_context = nil)
         super
diff --git a/lib/chef/resource/script.rb b/lib/chef/resource/script.rb
index 93e30c6a0e..54468a534d 100644
--- a/lib/chef/resource/script.rb
+++ b/lib/chef/resource/script.rb
@@ -29,9 +29,9 @@ class Chef
       identity_attr :name
 
       description "Use the **script** resource to execute scripts using a specified interpreter, such as Bash, csh, Perl, Python, or Ruby."\
-                  " This resource may also use any of the actions and properties that are available to the execute resource. Commands"\
+                  " This resource may also use any of the actions and properties that are available to the **execute** resource. Commands"\
                   " that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the"\
-                  " environment in which they are run. Use not_if and only_if to guard this resource for idempotence."
+                  " environment in which they are run. Use `not_if` and `only_if` to guard this resource for idempotence."
 
       def initialize(name, run_context = nil)
         super
diff --git a/lib/chef/resource/yum_repository.rb b/lib/chef/resource/yum_repository.rb
index 3070075959..94d1a284fc 100644
--- a/lib/chef/resource/yum_repository.rb
+++ b/lib/chef/resource/yum_repository.rb
@@ -37,7 +37,7 @@ class Chef
         gpgkey 'http://artifacts.ourco.org/pub/yum/RPM-GPG-KEY-OURCO-8'
         action :create
       end
-      ```ruby
+      ```
 
       **Delete a repository**: