Improve resource descriptions and the rake task for docs generation

Bring in a few more copy edits that were done on the website and improve the rake task so that it better creates docs that match the formatting we want.

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

7 files changed, 17 insertions, 9 deletions

diff --git a/lib/chef/resource/breakpoint.rb b/lib/chef/resource/breakpoint.rb
index 6584aad882..0beb7152a0 100644
--- a/lib/chef/resource/breakpoint.rb
+++ b/lib/chef/resource/breakpoint.rb
@@ -27,7 +27,7 @@ class Chef
       provides :breakpoint, target_mode: true
       resource_name :breakpoint
 
-      description "Use the breakpoint resource to add breakpoints to recipes. Run the #{Chef::Dist::SHELL} in #{Chef::Dist::CLIENT} mode, and then use those breakpoints to debug recipes. Breakpoints are ignored by the #{Chef::Dist::CLIENT} during an actual #{Chef::Dist::CLIENT} run. That said, breakpoints are typically used to debug recipes only when running them in a non-production environment, after which they are removed from those recipes before the parent cookbook is uploaded to the Chef server."
+      description "Use the breakpoint resource to add breakpoints to recipes. Run the #{Chef::Dist::SHELL} in #{Chef::Dist::PRODUCT} mode, and then use those breakpoints to debug recipes. Breakpoints are ignored by the #{Chef::Dist::CLIENT} during an actual #{Chef::Dist::CLIENT} run. That said, breakpoints are typically used to debug recipes only when running them in a non-production environment, after which they are removed from those recipes before the parent cookbook is uploaded to the Chef server."
       introduced "12.0"
 
       default_action :break
diff --git a/lib/chef/resource/build_essential.rb b/lib/chef/resource/build_essential.rb
index 0fb06486d9..8d93e57aab 100644
--- a/lib/chef/resource/build_essential.rb
+++ b/lib/chef/resource/build_essential.rb
@@ -22,7 +22,7 @@ class Chef
       resource_name :build_essential
       provides(:build_essential) { true }
 
-      description "Use the build_essential resource to install packages required for compiling C software from source."
+      description "Use the build_essential resource to install the packages required for compiling C software from source."
       introduced "14.0"
       examples <<~DOC
         Install compilation packages
diff --git a/lib/chef/resource/sudo.rb b/lib/chef/resource/sudo.rb
index d282d92c5e..c045b1266b 100644
--- a/lib/chef/resource/sudo.rb
+++ b/lib/chef/resource/sudo.rb
@@ -30,7 +30,7 @@ class Chef
       description "Use the sudo resource to add or remove individual sudo entries using sudoers.d files."\
                   " Sudo version 1.7.2 or newer is required to use the sudo resource, as it relies on the"\
                   " '#includedir' directive introduced in version 1.7.2. This resource does not enforce"\
-                  " installation of the required sudo version. Supported releases of Ubuntu, SuSE, Debian,"\
+                  " installation of the required sudo version. Chef-supported releases of Ubuntu, SuSE, Debian,"\
                   " and RHEL (6+) all support this feature."
       introduced "14.0"
 
diff --git a/lib/chef/resource/windows_env.rb b/lib/chef/resource/windows_env.rb
index 27bdbb74a8..d1e14b1d04 100644
--- a/lib/chef/resource/windows_env.rb
+++ b/lib/chef/resource/windows_env.rb
@@ -26,7 +26,7 @@ class Chef
       provides :windows_env
       provides :env # backwards compat with the pre-Chef 14 resource name
 
-      description "Use the 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."
 
       default_action :create
       allowed_actions :create, :delete, :modify
diff --git a/lib/chef/resource/windows_feature.rb b/lib/chef/resource/windows_feature.rb
index cc80284019..c1edcc002b 100644
--- a/lib/chef/resource/windows_feature.rb
+++ b/lib/chef/resource/windows_feature.rb
@@ -24,7 +24,7 @@ class Chef
       resource_name :windows_feature
       provides(:windows_feature) { true }
 
-      description "Use the windows_feature resource to add, remove or entirely delete Windows features and roles. This resource calls the 'windows_feature_dism' or 'windows_feature_powershell' resources depending on the specified installation method and defaults to dism, which is available on both Workstation and Server editions of Windows."
+      description "Use the windows_feature resource to add, remove or entirely delete Windows features and roles. This resource calls the 'windows_feature_dism' or 'windows_feature_powershell' resources depending on the specified installation method, and defaults to DISM, which is available on both Workstation and Server editions of Windows."
       introduced "14.0"
 
       property :feature_name, [Array, String],
@@ -35,7 +35,7 @@ class Chef
         description: "Specify a local repository for the feature install."
 
       property :all, [TrueClass, FalseClass],
-        description: "Install all sub features.",
+        description: "Install all sub-features.",
         default: false
 
       property :management_tools, [TrueClass, FalseClass],
diff --git a/lib/chef/resource/windows_feature_powershell.rb b/lib/chef/resource/windows_feature_powershell.rb
index 5cdbe1f74c..7d454a23bb 100644
--- a/lib/chef/resource/windows_feature_powershell.rb
+++ b/lib/chef/resource/windows_feature_powershell.rb
@@ -27,7 +27,7 @@ class Chef
       resource_name :windows_feature_powershell
       provides(:windows_feature_powershell) { true }
 
-      description "Use the windows_feature_powershell resource to add, remove, or entirely delete Windows features and roles using PowerShell. This resource offers significant speed benefits over the windows_feature_dism resource, but requires installing the Remote Server Administration Tools on non-server releases of Windows."
+      description "Use the windows_feature_powershell resource to add, remove, or entirely delete Windows features and roles using PowerShell. This resource offers significant speed benefits over the windows_feature_dism resource, but requires installation of the Remote Server Administration Tools on non-server releases of Windows."
       introduced "14.0"
 
       property :feature_name, [Array, String],
diff --git a/tasks/docs.rb b/tasks/docs.rb
index 8fa56e9e09..643eaee7a6 100755
--- a/tasks/docs.rb
+++ b/tasks/docs.rb
@@ -24,7 +24,9 @@ namespace :docs_site do
       return nil if default.nil? || default == "" || default == "lazy default"
 
       if default.is_a?(String)
-        return default.inspect unless default[0] == ":"
+
+        # .inspect wraps the value in quotes which we want for strings, but not sentences or symbols as strings
+        return default.inspect unless default[0] == ":" || default.end_with?('.')
       end
       default
     end
@@ -101,7 +103,13 @@ namespace :docs_site do
     def bolded_description(name, description)
       return nil if description.nil? # handle resources missing descriptions
 
-      description.gsub( "#{name} ", "**#{name}** ").split("Note: ").first.strip
+      # we only want to bold occurences of the resource name in the first 5 words so treat it as an array
+      desc_array = description.split(" ")
+
+      desc_array = desc_array[0..4].map! { |x| name == x ? "**#{x}**" : x } + desc_array[5..-1]
+
+      # strip out notes and return just the description
+      desc_array.join(" ").split("Note: ").first.strip
     end
 
     def note_text(description)