diff options
author | Tim Smith <tsmith@chef.io> | 2021-02-07 11:52:51 -0800 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-02-07 11:52:51 -0800 |
commit | 00c097c01d94595654d3c1c153326f99580119a2 (patch) | |
tree | 9711a7541691454fae9a9d26f79a4c4d3d110ef9 | |
parent | a221b9423b20084072ad91db4912a2be729e6d11 (diff) | |
parent | 15489c9ad32f5f83b0be49bb11fd74927c29f2eb (diff) | |
download | chef-00c097c01d94595654d3c1c153326f99580119a2.tar.gz |
Merge pull request #10992 from chef/more_docs
Signed-off-by: Tim Smith <tsmith@chef.io>
-rw-r--r-- | RELEASE_NOTES.md | 2 | ||||
-rw-r--r-- | lib/chef/resource/windows_env.rb | 9 | ||||
-rw-r--r-- | lib/chef/resource/windows_security_policy.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/windows_share.rb | 8 | ||||
-rwxr-xr-x | tasks/docs.rb | 19 |
5 files changed, 22 insertions, 18 deletions
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 4464caa95e..d0c85ef380 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -61,7 +61,7 @@ Note: In the upcoming release of Chef Workstation, you'll be able to skip the `b #### Knife Bootstrapping Without Sudo -The `knife boostrap` command now supports elevating privileges on systems without `sudo` by using the `su` command instead. Use the new `--su-user` and `--su-password` flags to specify credentials for `su`. +The `knife bootstrap` command now supports elevating privileges on systems without `sudo` by using the `su` command instead. Use the new `--su-user` and `--su-password` flags to specify credentials for `su`. ### Resource Updates diff --git a/lib/chef/resource/windows_env.rb b/lib/chef/resource/windows_env.rb index ab65465ed6..7620e90bad 100644 --- a/lib/chef/resource/windows_env.rb +++ b/lib/chef/resource/windows_env.rb @@ -19,6 +19,7 @@ require_relative "../resource" require_relative "../mixin/windows_env_helper" +require "chef-utils/dist" unless defined?(ChefUtils::Dist) class Chef class Resource @@ -28,7 +29,7 @@ class Chef provides :windows_env provides :env # backwards compat with the pre-Chef 14 resource name - description "Use the **windows_env** resource to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft Windows must be restarted before the environment key will be available to the Task Scheduler." + description "Use the **windows_env** resource to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft Windows must be restarted before the environment key will be available to the Task Scheduler.\nThis resource was previously called the **env** resource; its name was updated in #{ChefUtils::Dist::Infra::PRODUCT} 14.0 to reflect the fact that only Windows is supported. Existing cookbooks using `env` will continue to function, but should be updated to use the new name. Note: On UNIX-based systems, the best way to manipulate environment keys is with the `ENV` variable in Ruby; however, this approach does not have the same permanent effect as using the windows_env resource." examples <<~DOC **Set an environment variable**: @@ -192,7 +193,7 @@ class Chef end end - action :create do + action :create, description: "Create an environment variable. If an environment variable already exists (but does not match), update that environment variable to match." do if key_exists? if requires_modify_or_create? modify_env @@ -206,7 +207,7 @@ class Chef end end - action :delete do + action :delete, description: "Delete an environment variable." do if ( ENV[new_resource.key_name] || key_exists? ) && !delete_element delete_env logger.info("#{new_resource} deleted") @@ -214,7 +215,7 @@ class Chef end end - action :modify do + action :modify, description: "Modify an existing environment variable. This prepends the new value to the existing value, using the delimiter specified by the `delim` property." do if key_exists? if requires_modify_or_create? modify_env diff --git a/lib/chef/resource/windows_security_policy.rb b/lib/chef/resource/windows_security_policy.rb index 78d56e2e46..980b59a0ca 100644 --- a/lib/chef/resource/windows_security_policy.rb +++ b/lib/chef/resource/windows_security_policy.rb @@ -98,7 +98,7 @@ class Chef secvalue current_state[desired.secoption.to_s] end - action :set do + action :set, description: "Set the Windows security policy" do converge_if_changed :secvalue do security_option = new_resource.secoption security_value = new_resource.secvalue diff --git a/lib/chef/resource/windows_share.rb b/lib/chef/resource/windows_share.rb index fe1e976747..fca63ade05 100644 --- a/lib/chef/resource/windows_share.rb +++ b/lib/chef/resource/windows_share.rb @@ -192,9 +192,7 @@ class Chef name end - action :create do - description "Create and modify Windows shares." - + action :create, description: "Create or modify a Windows share" do # we do this here instead of requiring the property because :delete doesn't need path set raise "No path property set" unless new_resource.path @@ -218,9 +216,7 @@ class Chef end end - action :delete do - description "Delete an existing Windows share." - + action :delete, description: "Delete an existing Windows share" do if current_resource.nil? Chef::Log.debug("#{new_resource.share_name} does not exist - nothing to do") else diff --git a/tasks/docs.rb b/tasks/docs.rb index 0a31ead498..907d3c1ba4 100755 --- a/tasks/docs.rb +++ b/tasks/docs.rb @@ -132,8 +132,8 @@ namespace :docs_site do # # @return [Hash] # - def action_list(actions) - actions = actions.map { |k, v| [k.to_sym, { "markdown" => v } ] }.to_h + def action_list(actions, default_action) + actions = actions.map { |k, v| [k.to_sym, { "markdown" => k == default_action.first ? "#{v} (default)" : v } ] }.to_h actions[:nothing] = { "shortcode" => "resources_common_actions_nothing.md" } actions end @@ -153,7 +153,7 @@ namespace :docs_site do values["default_value"] = default_val unless default_val.nil? values["new_in"] = property["introduced"] unless property["introduced"].nil? values["allowed_values"] = property["equal_to"].join(", ") unless property["equal_to"].empty? - values["description_list"] = [{ "markdown" => property["description"] }] + values["description_list"] = split_description_values(property["description"]) values end end @@ -221,7 +221,7 @@ namespace :docs_site do # 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(name, text) + def split_description_values(text) return [{ "markdown" => nil }] if text.nil? description_pattern = /(Note:|Warning:)?((?:(?!Note:|Warning:).)*)/m @@ -246,6 +246,13 @@ namespace :docs_site do end end + description + end + + # takes the resource description text, splits out warning/note fields and then adds multipackage based notes when appropriate + def build_resource_description(name, text) + description = split_description_values(text) + # if we're on a package resource, depending on the OS we want to inject a warning / note that you can just use 'package' instead description << { "notes_resource_based_on_package" => true } if %w{apt_package bff_package dnf_package homebrew_package ips_package openbsd_package pacman_package portage_package smartos_package windows_package yum_package zypper_package pacman_package freebsd_package}.include?(name) @@ -265,12 +272,12 @@ namespace :docs_site do r.merge!(special_properties(name)) r["resource"] = name - r["resource_description_list"] = build_description(name, data["description"]) + r["resource_description_list"] = build_resource_description(name, 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 r["syntax_full_properties_list"] = friendly_full_property_list(name, properties) - r["actions_list"] = action_list(data["actions"]) + r["actions_list"] = action_list(data["actions"], data["default_action"] ) r["properties_list"] = properties_list(properties) r["examples"] = data["examples"] |