Merge pull request #10992 from chef/more_docs

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

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"]