Merge pull request #10024 from chef/resource-doc-updates

Resource doc updates

3 files changed, 125 insertions, 43 deletions

diff --git a/lib/chef/resource/chef_gem.rb b/lib/chef/resource/chef_gem.rb
index 664144619c..b44f9e1771 100644
--- a/lib/chef/resource/chef_gem.rb
+++ b/lib/chef/resource/chef_gem.rb
@@ -22,26 +22,59 @@ require_relative "../dist"
 
 class Chef
   class Resource
-    # Use the chef_gem resource to install a gem only for the instance of Ruby that is dedicated to the chef-client.
-    # When a gem is installed from a local file, it must be added to the node using the remote_file or cookbook_file
-    # resources.
-    #
-    # The chef_gem resource works with all of the same properties and options as the gem_package resource, but does not
-    # accept the gem_binary property because it always uses the CurrentGemEnvironment under which the chef-client is
-    # running. In addition to performing actions similar to the gem_package resource, the chef_gem resource does the
-    # following:
-    #  - Runs its actions immediately, before convergence, allowing a gem to be used in a recipe immediately after it is
-    #    installed
-    #  - Runs Gem.clear_paths after the action, ensuring that gem is aware of changes so that it can be required
-    #    immediately after it is installed
-
-    require_relative "gem_package"
-    require_relative "../dist"
-
     class ChefGem < Chef::Resource::Package::GemPackage
       unified_mode true
       provides :chef_gem
 
+      description <<~DESC
+        Use the **chef_gem** resource to install a gem only for the instance of Ruby that is dedicated to the #{Chef::Dist::CLIENT}.
+        When a gem is installed from a local file, it must be added to the node using the **remote_file** or **cookbook_file** resources.
+
+        The **chef_gem** resource works with all of the same properties and options as the **gem_package** resource, but does not
+        accept the `gem_binary` property because it always uses the `CurrentGemEnvironment` under which the `#{Chef::Dist::CLIENT}` is
+        running. In addition to performing actions similar to the **gem_package** resource, the **chef_gem** resource does the
+        following:
+        - Runs its actions immediately, before convergence, allowing a gem to be used in a recipe immediately after it is installed.
+        - Runs `Gem.clear_paths` after the action, ensuring that gem is aware of changes so that it can be required immediately after it is installed.
+
+        Warning: The **chef_gem** and **gem_package** resources are both used to install Ruby gems. For any machine on which #{Chef::Dist::PRODUCT} is
+        installed, there are two instances of Ruby. One is the standard, system-wide instance of Ruby and the other is a dedicated instance that is
+        available only to #{Chef::Dist::PRODUCT}.
+        Use the **chef_gem** resource to install gems into the instance of Ruby that is dedicated to #{Chef::Dist::PRODUCT}.
+        Use the **gem_package** resource to install all other gems (i.e. install gems system-wide).
+      DESC
+
+      examples <<~EXAMPLES
+        **Compile time vs. converge time installation of gems**
+
+        To install a gem while #{Chef::Dist::PRODUCT} is configuring the node (the converge phase), set the `compile_time` property to `false`:
+        ```ruby
+        chef_gem 'right_aws' do
+          compile_time false
+          action :install
+        end
+        ```
+
+        To install a gem while the resource collection is being built (the compile phase), set the `compile_time` property to `true`:
+        ```ruby
+        chef_gem 'right_aws' do
+          compile_time true
+          action :install
+        end
+        ```
+
+        Install MySQL for Chef
+        ```ruby
+        apt_update
+
+        build_essential 'install compilation tools' do
+          compile_time true
+        end
+
+        chef_gem 'mysql'
+        ```
+      EXAMPLES
+
       property :package_name, String,
         description: "An optional property to set the package name if it differs from the resource block's name.",
         identity: true
@@ -49,11 +82,14 @@ class Chef
       property :version, String,
         description: "The version of a package to be installed or upgraded."
 
-      property :gem_binary, default: "#{RbConfig::CONFIG["bindir"]}/gem", default_description: "The `gem` binary included with #{Chef::Dist::PRODUCT}.",
-                            description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by #{Chef::Dist::PRODUCT} will be installed.",
-                            callbacks: {
-                 "The chef_gem resource is restricted to the current gem environment, use gem_package to install to other environments." => proc { |v| v == "#{RbConfig::CONFIG["bindir"]}/gem" },
-               }
+      property :gem_binary, String,
+        default: "#{RbConfig::CONFIG["bindir"]}/gem",
+        default_description: "The `gem` binary included with #{Chef::Dist::PRODUCT}.",
+        description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by #{Chef::Dist::PRODUCT} will be used.",
+        callbacks: {
+          "The `chef_gem` resource is restricted to the current gem environment, use `gem_package` to install to other environments." =>
+            proc { |v| v == "#{RbConfig::CONFIG["bindir"]}/gem" },
+        }
     end
   end
 end
diff --git a/lib/chef/resource/gem_package.rb b/lib/chef/resource/gem_package.rb
index def92bd34d..05f8611233 100644
--- a/lib/chef/resource/gem_package.rb
+++ b/lib/chef/resource/gem_package.rb
@@ -25,7 +25,40 @@ class Chef
       unified_mode true
       provides :gem_package
 
-      description "Use the **gem_package** resource to manage gem packages that are only included in recipes. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources."
+      description <<~DESC
+        Use the **gem_package** resource to manage gem packages that are only included in recipes.
+        When a gem is installed from a local file, it must be added to the node using the **remote_file** or **cookbook_file** resources.
+
+        Note: The **gem_package** resource must be specified as `gem_package` and cannot be shortened to `package` in a recipe.
+
+        Warning: The **chef_gem** and **gem_package** resources are both used to install Ruby gems. For any machine on which #{Chef::Dist::PRODUCT} is
+        installed, there are two instances of Ruby. One is the standard, system-wide instance of Ruby and the other is a dedicated instance that is
+        available only to #{Chef::Dist::PRODUCT}.
+        Use the **chef_gem** resource to install gems into the instance of Ruby that is dedicated to #{Chef::Dist::PRODUCT}.
+        Use the **gem_package** resource to install all other gems (i.e. install gems system-wide).
+      DESC
+
+      examples <<~EXAMPLES
+        The following examples demonstrate various approaches for using the **gem_package** resource in recipes:
+
+        **Install a gem file from the local file system**
+
+        ```ruby
+        gem_package 'right_aws' do
+          source '/tmp/right_aws-1.11.0.gem'
+          action :install
+        end
+        ```
+
+        **Use the `ignore_failure` common attribute**
+
+        ```ruby
+        gem_package 'syntax' do
+          action :install
+          ignore_failure true
+        end
+        ```
+      EXAMPLES
 
       property :package_name, String,
         description: "An optional property to set the package name if it differs from the resource block's name.",
@@ -53,7 +86,7 @@ class Chef
         default: lazy { Chef::Config[:clear_gem_sources] }, desired_state: false
 
       property :gem_binary, String, desired_state: false,
-        description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by #{Chef::Dist::PRODUCT} will be installed."
+        description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by #{Chef::Dist::PRODUCT} will be used."
 
       property :include_default_source, [ TrueClass, FalseClass, nil ],
         description: "Set to `false` to not include `Chef::Config[:rubygems_url]` in the sources.",
diff --git a/tasks/docs.rb b/tasks/docs.rb
index 954bfa6059..2327a928c7 100755
--- a/tasks/docs.rb
+++ b/tasks/docs.rb
@@ -112,20 +112,6 @@ namespace :docs_site do
       fixed_arr.compact.join(", ")
     end
 
-    # split out notes from the description field. We didn't design a note syntax so we stick them in there
-    def note_text(description)
-      return nil if description.nil?
-
-      description.split("Note: ")[1]
-    end
-
-    # Returns description without embedded notes that may be present
-    def description_text(description)
-      return nil if description.nil?
-
-      description.split(" Note:")[0]
-    end
-
     # build the menu entry for this resource
     def build_menu_item(name)
       {
@@ -250,6 +236,38 @@ namespace :docs_site do
       properties
     end
 
+    # Breaks a block of text into the different sections expected for the description,
+    # using the markers "Note:" for "note" sections and "Warning:" for "warning" sections.
+    # TODO: has the limitation that the plain description section is assumed to come first,
+    # and is followed by one or more "note"s or "warning"s sections.
+    def build_description(text)
+      return [{ "markdown" => nil }] if text.nil?
+
+      description_pattern = /(Note:|Warning:)?((?:(?!Note:|Warning:).)*)/m
+
+      description = []
+
+      text.scan(description_pattern) do |preface, body|
+        body.strip!
+        next if body.empty?
+
+        element = { "markdown" => body }
+
+        case preface
+        when "Note:"
+          description << { "note" => element }
+        when "Warning:"
+          description << { "warning" => element }
+        when nil
+          description << element
+        else
+          raise "Unexpected thing happened! preface: '#{preface}', body: '#{body}'"
+        end
+      end
+
+      description
+    end
+
     # the main method that builds what will become the yaml file
     def build_resource_data(name, data)
       properties = data["properties"].reject { |v| v["name"] == "name" || v["deprecated"] }.sort_by! { |v| v["name"] }
@@ -266,12 +284,7 @@ namespace :docs_site do
       r["resource"] = name
       r["aliases"] = ["/resource_#{name}.html"]
       r["menu"] = build_menu_item(name)
-      r["resource_description_list"] = {}
-      r["resource_description_list"] = [{ "markdown" => description_text(data["description"]) }]
-
-      # if the description contained a note then add it
-      r["resource_description_list"] << { "note" => { "markdown" => note_text(data["description"]) } } unless note_text(data["description"]).nil?
-
+      r["resource_description_list"] = build_description(data["description"])
       r["resource_new_in"] = data["introduced"] unless data["introduced"].nil?
       r["syntax_full_code_block"] = generate_resource_block(name, properties, data["default_action"])
       r["syntax_properties_list"] = nil