diff options
author | Tim Smith <tsmith@chef.io> | 2020-06-22 14:08:16 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-06-22 14:08:16 -0700 |
commit | c9e40653c4ddd4a4a20e7a7e371fbedf27072a72 (patch) | |
tree | 0a23cd548f3f225a5d825773312a7b6718bc3f26 | |
parent | 7f23b35885cd842092a25f8607658384bfd01528 (diff) | |
parent | 1efd520e4c59b2325c781dafd10ddfcc1b7733ee (diff) | |
download | chef-c9e40653c4ddd4a4a20e7a7e371fbedf27072a72.tar.gz |
Merge pull request #10024 from chef/resource-doc-updates
Resource doc updates
-rw-r--r-- | lib/chef/resource/chef_gem.rb | 78 | ||||
-rw-r--r-- | lib/chef/resource/gem_package.rb | 37 | ||||
-rwxr-xr-x | tasks/docs.rb | 53 |
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 |