Merge pull request #9767 from chef/more_docs

More improvements to the docs generation

24 files changed, 100 insertions, 76 deletions

diff --git a/lib/chef/resource/apt_package.rb b/lib/chef/resource/apt_package.rb
index 148255c47f..9889843e26 100644
--- a/lib/chef/resource/apt_package.rb
+++ b/lib/chef/resource/apt_package.rb
@@ -29,7 +29,7 @@ class Chef
       description "Use the apt_package resource to manage packages on Debian and Ubuntu platforms."
 
       property :default_release, String,
-        description: "The default release. For example: stable.",
+        description: "The default release. For example: `stable`.",
         desired_state: false
 
       property :overwrite_config_files, [TrueClass, FalseClass],
diff --git a/lib/chef/resource/apt_preference.rb b/lib/chef/resource/apt_preference.rb
index 9a661ce37d..1c910c99a5 100644
--- a/lib/chef/resource/apt_preference.rb
+++ b/lib/chef/resource/apt_preference.rb
@@ -36,7 +36,7 @@ class Chef
         validation_message: "The provided package name is not valid. Package names can only contain alphanumeric characters as well as _, -, +, or *!"
 
       property :glob, String,
-        description: "Pin by glob() expression or with regular expressions surrounded by /."
+        description: "Pin by a `glob()` expression or with a regular expression surrounded by `/`."
 
       property :pin, String,
         description: "The package version or repository to pin.",
diff --git a/lib/chef/resource/apt_repository.rb b/lib/chef/resource/apt_repository.rb
index 7e56a4b3af..1a6ea10522 100644
--- a/lib/chef/resource/apt_repository.rb
+++ b/lib/chef/resource/apt_repository.rb
@@ -115,15 +115,15 @@ class Chef
         description: "The base of the Debian distribution."
 
       property :distribution, [ String, nil, FalseClass ],
-        description: "Usually a distribution's codename, such as xenial, bionic, or focal.",
+        description: "Usually a distribution's codename, such as `xenial`, `bionic`, or `focal`.",
         default: lazy { node["lsb"]["codename"] }, default_description: "The LSB codename of the node such as 'focal'."
 
       property :components, Array,
         description: "Package groupings, such as 'main' and 'stable'.",
-        default: lazy { [] }, default_description: "'main' if using a PPA repository."
+        default: lazy { [] }, default_description: "`main` if using a PPA repository."
 
       property :arch, [String, nil, FalseClass],
-        description: "Constrain packages to a particular CPU architecture such as 'i386' or 'amd64'."
+        description: "Constrain packages to a particular CPU architecture such as `i386` or `amd64`."
 
       property :trusted, [TrueClass, FalseClass],
         description: "Determines whether you should treat all packages from this repository as authenticated regardless of signature.",
diff --git a/lib/chef/resource/apt_update.rb b/lib/chef/resource/apt_update.rb
index 2fa7c16ddb..a2ca6aa5e0 100644
--- a/lib/chef/resource/apt_update.rb
+++ b/lib/chef/resource/apt_update.rb
@@ -46,7 +46,7 @@ class Chef
       property :name, String, default: ""
 
       property :frequency, Integer,
-        description: "Determines how frequently (in seconds) APT repository updates are made. Use this property when the :periodic action is specified.",
+        description: "Determines how frequently (in seconds) APT repository updates are made. Use this property when the `:periodic` action is specified.",
         default: 86_400
 
       default_action :periodic
diff --git a/lib/chef/resource/archive_file.rb b/lib/chef/resource/archive_file.rb
index b525286c06..b288cb4885 100644
--- a/lib/chef/resource/archive_file.rb
+++ b/lib/chef/resource/archive_file.rb
@@ -60,11 +60,11 @@ class Chef
         required: true
 
       property :options, [Array, Symbol],
-        description: "An array of symbols representing extraction flags. Example: :no_overwrite to prevent overwriting files on disk. By default, this properly sets :time which preserves the modification timestamps of files in the archive when writing them to disk.",
+        description: "An array of symbols representing extraction flags. Example: `:no_overwrite` to prevent overwriting files on disk. By default, this properly sets `:time` which preserves the modification timestamps of files in the archive when writing them to disk.",
         default: lazy { [:time] }
 
       property :overwrite, [TrueClass, FalseClass, :auto],
-        description: "Should the resource overwrite the destination file contents if they already exist? If set to :auto the date stamp of files within the archive will be compared to those on disk and disk contents will be overwritten if they differ. This may cause unintended consequences if disk date stamps are changed between runs, which will result in the files being overwritten during each client run. Make sure to properly test any change to this property.",
+        description: "Should the resource overwrite the destination file contents if they already exist? If set to `:auto` the date stamp of files within the archive will be compared to those on disk and disk contents will be overwritten if they differ. This may cause unintended consequences if disk date stamps are changed between runs, which will result in the files being overwritten during each client run. Make sure to properly test any change to this property.",
         default: false
 
       # backwards compatibility for the legacy cookbook names
diff --git a/lib/chef/resource/chef_client_cron.rb b/lib/chef/resource/chef_client_cron.rb
index 48655f1a92..5ef68e5b55 100644
--- a/lib/chef/resource/chef_client_cron.rb
+++ b/lib/chef/resource/chef_client_cron.rb
@@ -133,7 +133,7 @@ class Chef
 
       property :environment, Hash,
         default: lazy { {} },
-        description: "A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of ``({'ENV_VARIABLE' => 'VALUE'})``."
+        description: "A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of `({'ENV_VARIABLE' => 'VALUE'})`."
 
       action :add do
         # TODO: Replace this with a :create_if_missing action on directory when that exists
diff --git a/lib/chef/resource/chef_client_systemd_timer.rb b/lib/chef/resource/chef_client_systemd_timer.rb
index 988ec01364..b174faef14 100644
--- a/lib/chef/resource/chef_client_systemd_timer.rb
+++ b/lib/chef/resource/chef_client_systemd_timer.rb
@@ -92,7 +92,7 @@ class Chef
         default: lazy { [] }
 
       property :environment, Hash,
-        description: "A Hash containing additional arbitrary environment variables under which the systemd timer will be run in the form of ``({'ENV_VARIABLE' => 'VALUE'})``.",
+        description: "A Hash containing additional arbitrary environment variables under which the systemd timer will be run in the form of `({'ENV_VARIABLE' => 'VALUE'})`.",
         default: lazy { {} }
 
       action :add do
diff --git a/lib/chef/resource/chocolatey_package.rb b/lib/chef/resource/chocolatey_package.rb
index 9dc3d2d7a5..7beefb5ef5 100644
--- a/lib/chef/resource/chocolatey_package.rb
+++ b/lib/chef/resource/chocolatey_package.rb
@@ -35,7 +35,7 @@ class Chef
         end
         ```
 
-        Install a package with options with Chocolatey's ``--checksum`` option
+        Install a package with options with Chocolatey's `--checksum` option
         ```ruby
         chocolatey_package 'name of package' do
           options '--checksum 1234567890'
diff --git a/lib/chef/resource/cron.rb b/lib/chef/resource/cron.rb
index d010cfc9bf..a274bbeefe 100644
--- a/lib/chef/resource/cron.rb
+++ b/lib/chef/resource/cron.rb
@@ -93,16 +93,16 @@ class Chef
         equal_to: Chef::Provider::Cron::SPECIAL_TIME_VALUES
 
       property :mailto, String,
-        description: "Set the MAILTO environment variable."
+        description: "Set the `MAILTO` environment variable."
 
       property :path, String,
-        description: "Set the PATH environment variable."
+        description: "Set the `PATH` environment variable."
 
       property :home, String,
-        description: "Set the HOME environment variable."
+        description: "Set the `HOME` environment variable."
 
       property :shell, String,
-        description: "Set the SHELL environment variable."
+        description: "Set the `SHELL` environment variable."
 
       property :command, String,
         description: "The command to be run, or the path to a file that contains the command to be run.",
@@ -113,14 +113,14 @@ class Chef
         default: "root"
 
       property :environment, Hash,
-        description: "A Hash of environment variables in the form of ({'ENV_VARIABLE' => 'VALUE'}).",
+        description: "A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of `({'ENV_VARIABLE' => 'VALUE'})`.",
         default: lazy { {} }
 
       TIMEOUT_OPTS = %w{duration preserve-status foreground kill-after signal}.freeze
       TIMEOUT_REGEX = /\A\S+/.freeze
 
       property :time_out, Hash,
-        description: "A Hash of timeouts in the form of ({'OPTION' => 'VALUE'}).
+        description: "A Hash of timeouts in the form of `({'OPTION' => 'VALUE'})`.
         Accepted valid options are:
         preserve-status (BOOL, default: 'false'),
         foreground (BOOL, default: 'false'),
diff --git a/lib/chef/resource/cron_d.rb b/lib/chef/resource/cron_d.rb
index 03ce19708f..94e855e51f 100644
--- a/lib/chef/resource/cron_d.rb
+++ b/lib/chef/resource/cron_d.rb
@@ -27,7 +27,7 @@ class Chef
       provides :cron_d
 
       introduced "14.4"
-      description "Use the cron_d resource to manage cron definitions in /etc/cron.d. This is similar to the 'cron' resource, but it does not use the monolithic /etc/crontab file."
+      description "Use the cron_d resource to manage cron job files in the /etc/cron.d directory. This is similar to the 'cron' resource, but it does not use the monolithic /etc/crontab file."
       examples <<~DOC
         To run a program on the fifth hour of the day
         ```ruby
@@ -78,7 +78,7 @@ class Chef
         description: "An optional property to set the cron name if it differs from the resource block's name.",
         name_property: true
 
-      property :cookbook, String, desired_state: false
+      property :cookbook, String, desired_state: false, skip_docs: true
 
       property :predefined_value, String,
         description: "Schedule your cron job with one of the special predefined value instead of ** * pattern.",
@@ -123,29 +123,29 @@ class Chef
         default: "root"
 
       property :mailto, String,
-        description: "Set the MAILTO environment variable in the cron.d file."
+        description: "Set the `MAILTO` environment variable in the cron.d file."
 
       property :path, String,
-        description: "Set the PATH environment variable in the cron.d file."
+        description: "Set the `PATH` environment variable in the cron.d file."
 
       property :home, String,
-        description: "Set the HOME environment variable in the cron.d file."
+        description: "Set the `HOME` environment variable in the cron.d file."
 
       property :shell, String,
-        description: "Set the SHELL environment variable in the cron.d file."
+        description: "Set the `SHELL` environment variable in the cron.d file."
 
       property :comment, String,
         description: "A comment to place in the cron.d file."
 
       property :environment, Hash,
-        description: "A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of ``({'ENV_VARIABLE' => 'VALUE'})``.",
+        description: "A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of `({'ENV_VARIABLE' => 'VALUE'})`.",
         default: lazy { {} }
 
       TIMEOUT_OPTS = %w{duration preserve-status foreground kill-after signal}.freeze
       TIMEOUT_REGEX = /\A\S+/.freeze
 
       property :time_out, Hash,
-        description: "A Hash of timeouts in the form of ({'OPTION' => 'VALUE'}).
+        description: "A Hash of timeouts in the form of `({'OPTION' => 'VALUE'})`.
         Accepted valid options are:
         preserve-status (BOOL, default: 'false'),
         foreground (BOOL, default: 'false'),
@@ -175,7 +175,7 @@ class Chef
         default: "0600"
 
       property :random_delay, Integer,
-        description: "Set the RANDOM_DELAY environment variable in the cron.d file."
+        description: "Set the `RANDOM_DELAY` environment variable in the cron.d file."
 
       # warn if someone passes the deprecated cookbook property
       def after_created
diff --git a/lib/chef/resource/dmg_package.rb b/lib/chef/resource/dmg_package.rb
index a5d331c24c..14b16a9284 100644
--- a/lib/chef/resource/dmg_package.rb
+++ b/lib/chef/resource/dmg_package.rb
@@ -56,31 +56,31 @@ class Chef
       DOC
 
       property :app, String,
-        description: "The name of the application as it appears in the /Volumes directory if it differs from the resource block's name.",
+        description: "The name of the application as it appears in the `/Volumes` directory if it differs from the resource block's name.",
         name_property: true
 
       property :source, String,
-        description: "The remote URL that is used to download the .dmg file, if specified."
+        description: "The remote URL that is used to download the `.dmg` file, if specified."
 
       property :file, String,
-        description: "The full path to the .dmg file on the local system."
+        description: "The full path to the `.dmg` file on the local system."
 
       property :owner, [String, Integer],
         description: "The user that should own the package installation."
 
       property :destination, String,
-        description: "The directory to copy the .app into.",
+        description: "The directory to copy the `.app` into.",
         default: "/Applications"
 
       property :checksum, String,
-        description: "The sha256 checksum of the .dmg file to download."
+        description: "The sha256 checksum of the `.dmg` file to download."
 
       property :volumes_dir, String,
-        description: "The directory under /Volumes where the dmg is mounted if it differs from the name of the .dmg file.",
+        description: "The directory under `/Volumes` where the `dmg` is mounted if it differs from the name of the `.dmg` file.",
         default: lazy { app }, default_description: "The value passed for the application name."
 
       property :dmg_name, String,
-        description: "The name of the .dmg file if it differs from that of the app, or if the name has spaces.",
+        description: "The name of the `.dmg` file if it differs from that of the app, or if the name has spaces.",
         desired_state: false,
         default: lazy { app }, default_description: "The value passed for the application name."
 
@@ -90,18 +90,18 @@ class Chef
         default: "app", desired_state: false
 
       property :package_id, String,
-        description: "The package ID that is registered with pkgutil when a pkg or mpkg is installed."
+        description: "The package ID that is registered with `pkgutil` when a `pkg` or `mpkg` is installed."
 
       property :dmg_passphrase, String,
-        description: "Specify a passphrase to be used to decrypt the .dmg file during the mount process.",
+        description: "Specify a passphrase to be used to decrypt the `.dmg` file during the mount process.",
         desired_state: false
 
       property :accept_eula, [TrueClass, FalseClass],
-        description: "Specify whether to accept the EULA. Certain dmgs require acceptance of EULA before mounting.",
+        description: "Specify whether to accept the EULA. Certain dmg files require acceptance of EULA before mounting.",
         default: false, desired_state: false
 
       property :headers, Hash,
-        description: "Allows custom HTTP headers (like cookies) to be set on the remote_file resource.",
+        description: "Allows custom HTTP headers (like cookies) to be set on the `remote_file` resource.",
         desired_state: false
 
       property :allow_untrusted, [TrueClass, FalseClass],
diff --git a/lib/chef/resource/file.rb b/lib/chef/resource/file.rb
index a2f2009bd0..930e044846 100644
--- a/lib/chef/resource/file.rb
+++ b/lib/chef/resource/file.rb
@@ -73,7 +73,7 @@ class Chef
       property :diff, [ String, nil ], desired_state: false, skip_docs: true
 
       property :force_unlink, [ TrueClass, FalseClass ], desired_state: false, default: false,
-               description: "How the #{Chef::Dist::CLIENT} handles certain situations when the target file turns out not to be a file. For example, when a target file is actually a symlink. Set to true for the #{Chef::Dist::CLIENT} delete the non-file target and replace it with the specified file. Set to false for the #{Chef::Dist::CLIENT} to raise an error."
+               description: "How #{Chef::Dist::PRODUCT} handles certain situations when the target file turns out not to be a file. For example, when a target file is actually a symlink. Set to true for #{Chef::Dist::PRODUCT} to delete the non-file target and replace it with the specified file. Set to false for #{Chef::Dist::PRODUCT} to raise an error."
 
       property :manage_symlink_source, [ TrueClass, FalseClass ], desired_state: false,
                description: "Change the behavior of the file resource if it is pointed at a symlink. When this value is set to true, #{Chef::Dist::PRODUCT} will manage the symlink's permissions or will replace the symlink with a normal file if the resource has content. When this value is set to false, #{Chef::Dist::PRODUCT} will follow the symlink and will manage the permissions and content of symlink's target file. The default behavior is true but emits a warning that the default value will be changed to false in a future version; setting this explicitly to true or false suppresses this warning."
diff --git a/lib/chef/resource/gem_package.rb b/lib/chef/resource/gem_package.rb
index eda415526e..a5184f41d6 100644
--- a/lib/chef/resource/gem_package.rb
+++ b/lib/chef/resource/gem_package.rb
@@ -49,7 +49,7 @@ class Chef
         description: "Optional. The URL, or list of URLs, at which the gem package is located. This list is added to the source configured in Chef::Config[:rubygems_url] (see also include_default_source) to construct the complete list of rubygems sources. Users in an 'airgapped' environment should set Chef::Config[:rubygems_url] to their local RubyGems mirror."
 
       property :clear_sources, [ TrueClass, FalseClass, nil ],
-        description: "Set to 'true' to download a gem from the path specified by the source property (and not from RubyGems).",
+        description: "Set to 'true' to download a gem from the path specified by the `source` property (and not from RubyGems).",
         default: lazy { Chef::Config[:clear_gem_sources] }, desired_state: false
 
       property :gem_binary, String, desired_state: false,
diff --git a/lib/chef/resource/ifconfig.rb b/lib/chef/resource/ifconfig.rb
index 72e918b1e9..8d74b27fc6 100644
--- a/lib/chef/resource/ifconfig.rb
+++ b/lib/chef/resource/ifconfig.rb
@@ -45,11 +45,11 @@ class Chef
         description: "The hardware address for the network interface."
 
       property :mask, String,
-        description: "The decimal representation of the network mask. For example: 255.255.255.0."
+        description: "The decimal representation of the network mask. For example: `255.255.255.0`."
 
       property :family, String, default: "inet",
-               introduced: "14.0",
-               description: "Networking family option for Debian-based systems; for example: inet or inet6."
+        introduced: "14.0",
+        description: "Networking family option for Debian-based systems; for example: `inet` or `inet6`."
 
       property :inet_addr, String,
         description: "The Internet host address for the network interface."
@@ -81,11 +81,11 @@ class Chef
 
       property :ethtool_opts, String,
         introduced: "13.4",
-        description: "Options to be passed to ethtool(8). For example: -A eth0 autoneg off rx off tx off."
+        description: "Options to be passed to ethtool(8). For example: `-A eth0 autoneg off rx off tx off`."
 
       property :bonding_opts, String,
         introduced: "13.4",
-        description: "Bonding options to pass via BONDING_OPTS on RHEL and CentOS. For example: mode=active-backup miimon=100."
+        description: "Bonding options to pass via `BONDING_OPTS` on RHEL and CentOS. For example: `mode=active-backup miimon=100`."
 
       property :master, String,
         introduced: "13.4",
@@ -93,7 +93,7 @@ class Chef
 
       property :slave, String,
         introduced: "13.4",
-        description: "When set to yes, this device is controlled by the channel bonding interface that is specified via the master property."
+        description: "When set to `yes`, this device is controlled by the channel bonding interface that is specified via the `master` property."
 
       property :vlan, String,
         introduced: "14.4",
diff --git a/lib/chef/resource/user.rb b/lib/chef/resource/user.rb
index 6e414824e7..6f96cac980 100644
--- a/lib/chef/resource/user.rb
+++ b/lib/chef/resource/user.rb
@@ -55,7 +55,7 @@ class Chef
         default: false, desired_state: false
 
       property :manage_home, [ TrueClass, FalseClass ],
-        description: "Manage a user’s home directory.\nWhen used with the :create action, a user’s home directory is created based on HOME_DIR. If the home directory is missing, it is created unless CREATE_HOME in /etc/login.defs is set to no. When created, a skeleton set of files and subdirectories are included within the home directory.\nWhen used with the :modify action, a user’s home directory is moved to HOME_DIR. If the home directory is missing, it is created unless CREATE_HOME in /etc/login.defs is set to no. The contents of the user’s home directory are moved to the new location.",
+        description: "Manage a user's home directory.\nWhen used with the :create action, a user's home directory is created based on HOME_DIR. If the home directory is missing, it is created unless CREATE_HOME in /etc/login.defs is set to no. When created, a skeleton set of files and subdirectories are included within the home directory.\nWhen used with the :modify action, a user's home directory is moved to HOME_DIR. If the home directory is missing, it is created unless CREATE_HOME in /etc/login.defs is set to no. The contents of the user's home directory are moved to the new location.",
         default: false, desired_state: false
 
       property :force, [ TrueClass, FalseClass ],
diff --git a/lib/chef/resource/windows_auto_run.rb b/lib/chef/resource/windows_auto_run.rb
index dd8449be9e..63af080191 100644
--- a/lib/chef/resource/windows_auto_run.rb
+++ b/lib/chef/resource/windows_auto_run.rb
@@ -32,7 +32,7 @@ class Chef
 
       property :path, String,
         coerce: proc { |x| x.tr("/", "\\") }, # make sure we have windows paths for the registry
-        description: "The path to the program that will run at login. "
+        description: "The path to the program that will run at login."
 
       property :args, String,
         description: "Any arguments to be used with the program."
diff --git a/lib/chef/resource/windows_feature.rb b/lib/chef/resource/windows_feature.rb
index b90f96e79d..4a4179f944 100644
--- a/lib/chef/resource/windows_feature.rb
+++ b/lib/chef/resource/windows_feature.rb
@@ -42,7 +42,7 @@ class Chef
         default: false
 
       property :install_method, Symbol,
-        description: "The underlying installation method to use for feature installation. Specify ':windows_feature_dism' for DISM or ':windows_feature_powershell' for PowerShell.",
+        description: "The underlying installation method to use for feature installation. Specify `:windows_feature_dism` for DISM or `:windows_feature_powershell` for PowerShell.",
         equal_to: %i{windows_feature_dism windows_feature_powershell windows_feature_servermanagercmd},
         default: :windows_feature_dism
 
diff --git a/lib/chef/resource/windows_feature_dism.rb b/lib/chef/resource/windows_feature_dism.rb
index 3f29956dd1..276eb9cb1f 100644
--- a/lib/chef/resource/windows_feature_dism.rb
+++ b/lib/chef/resource/windows_feature_dism.rb
@@ -36,7 +36,7 @@ class Chef
         description: "Specify a local repository for the feature install."
 
       property :all, [TrueClass, FalseClass],
-        description: "Install all sub-features. When set to 'true', this is the equivalent of specifying the /All switch to dism.exe",
+        description: "Install all sub-features. When set to `true`, this is the equivalent of specifying the `/All` switch to `dism.exe`",
         default: false
 
       property :timeout, Integer,
diff --git a/lib/chef/resource/windows_feature_powershell.rb b/lib/chef/resource/windows_feature_powershell.rb
index d26dd95c91..522ffcf4a7 100644
--- a/lib/chef/resource/windows_feature_powershell.rb
+++ b/lib/chef/resource/windows_feature_powershell.rb
@@ -37,7 +37,7 @@ class Chef
         description: "Specify a local repository for the feature install."
 
       property :all, [TrueClass, FalseClass],
-        description: "Install all subfeatures. When set to 'true', this is the equivalent of specifying the '-InstallAllSubFeatures' switch with 'Add-WindowsFeature'.",
+        description: "Install all subfeatures. When set to `true`, this is the equivalent of specifying the `-InstallAllSubFeatures` switch with `Add-WindowsFeature`.",
         default: false
 
       property :timeout, Integer,
diff --git a/lib/chef/resource/windows_package.rb b/lib/chef/resource/windows_package.rb
index ccedd654bd..b0af2c6aef 100644
--- a/lib/chef/resource/windows_package.rb
+++ b/lib/chef/resource/windows_package.rb
@@ -79,7 +79,7 @@ class Chef
 
       property :checksum, String,
         desired_state: false, coerce: (proc { |c| c.downcase }),
-        description: "The SHA-256 checksum of the file. Use to prevent a file from being re-downloaded. When the local file matches the checksum, #{Chef::Dist::PRODUCT} does not download it. Use when a URL is specified by the source property."
+        description: "The SHA-256 checksum of the file. Use to prevent a file from being re-downloaded. When the local file matches the checksum, #{Chef::Dist::PRODUCT} does not download it. Use when a URL is specified by the `source` property."
 
       property :remote_file_attributes, Hash,
         desired_state: false,
diff --git a/lib/chef/resource/windows_pagefile.rb b/lib/chef/resource/windows_pagefile.rb
index e2d9590f64..c43838b932 100644
--- a/lib/chef/resource/windows_pagefile.rb
+++ b/lib/chef/resource/windows_pagefile.rb
@@ -34,7 +34,7 @@ class Chef
         description: "Configures whether the system manages the pagefile size."
 
       property :automatic_managed, [TrueClass, FalseClass],
-        description: "Enable automatic management of pagefile initial and maximum size. Setting this to true ignores 'initial_size' and 'maximum_size' properties.",
+        description: "Enable automatic management of pagefile initial and maximum size. Setting this to true ignores `initial_size` and `maximum_size` properties.",
         default: false
 
       property :initial_size, Integer,
diff --git a/lib/chef/resource/windows_task.rb b/lib/chef/resource/windows_task.rb
index a3a1e7bcda..2a2887ca0a 100644
--- a/lib/chef/resource/windows_task.rb
+++ b/lib/chef/resource/windows_task.rb
@@ -31,7 +31,7 @@ class Chef
       default_action :create
 
       property :task_name, String, regex: [%r{\A[^/\:\*\?\<\>\|]+\z}],
-               description: "An optional property to set the task name if it differs from the resource block's name. Example: 'Task Name' or '/Task Name'",
+               description: "An optional property to set the task name if it differs from the resource block's name. Example: `Task Name` or `/Task Name`",
                name_property: true
 
       property :command, String,
@@ -46,7 +46,7 @@ class Chef
         default_description: "The localized SYSTEM user for the node."
 
       property :password, String,
-        description: "The user’s password. The user property must be set if using this property."
+        description: "The user's password. The user property must be set if using this property."
 
       property :run_level, Symbol, equal_to: %i{highest limited},
                description: "Run with `:limited` or `:highest` privileges.",
@@ -89,13 +89,13 @@ class Chef
         description: "The Months of the year on which the task runs, such as: `JAN, FEB` or `*`. Multiple months should be comma delimited. e.g. `Jan, Feb, Mar, Dec`."
 
       property :idle_time, Integer,
-        description: "For `:on_idle` frequency, the time (in minutes) without user activity that must pass to trigger the task, from 1 - 999."
+        description: "For `:on_idle` frequency, the time (in minutes) without user activity that must pass to trigger the task, from `1` - `999`."
 
       property :random_delay, [String, Integer],
         description: "Delays the task up to a given time (in seconds)."
 
       property :execution_time_limit, [String, Integer],
-        description: "The maximum time the task will run. This field can accept either seconds or an ISO8601 duration value",
+        description: "The maximum time the task will run. This field accepts either seconds or an ISO8601 duration value.",
         default: "PT72H",
         default_description: "PT72H (72 hours in ISO8601 duration format)"
 
diff --git a/lib/chef/resource/yum_repository.rb b/lib/chef/resource/yum_repository.rb
index 20acfeb022..f0d2fb8329 100644
--- a/lib/chef/resource/yum_repository.rb
+++ b/lib/chef/resource/yum_repository.rb
@@ -64,7 +64,7 @@ class Chef
         description: "List of packages to exclude from updates or installs. This should be a space separated list. Shell globs using wildcards (eg. * and ?) are allowed."
 
       property :failovermethod, String,
-        description: "Method to determine how to switch to a new server if the current one fails, which can either be ``roundrobin`` or ``priority``. ``roundrobin`` randomly selects a URL out of the list of URLs to start with and proceeds through each of them as it encounters a failure contacting the host. ``priority`` starts from the first ``baseurl`` listed and reads through them sequentially.",
+        description: "Method to determine how to switch to a new server if the current one fails, which can either be `roundrobin` or `priority`. `roundrobin` randomly selects a URL out of the list of URLs to start with and proceeds through each of them as it encounters a failure contacting the host. `priority` starts from the first `baseurl` listed and reads through them sequentially.",
         equal_to: %w{priority roundrobin}
 
       property :fastestmirror_enabled, [TrueClass, FalseClass],
@@ -81,23 +81,23 @@ class Chef
                description: "Determines how upstream HTTP caches are instructed to handle any HTTP downloads that Yum does. This option can take the following values: all (all HTTP downloads should be cached), packages (only RPM package downloads should be cached, but not repository metadata downloads), or none (no HTTP downloads should be cached)"
 
       property :include_config, String,
-        description: "An external configuration file using the format 'url://to/some/location'."
+        description: "An external configuration file using the format `url://to/some/location`."
 
       property :includepkgs, String,
         description: "Inverse of exclude property. This is a list of packages you want to use from a repository. If this option lists only one package then that is all Yum will ever see from the repository."
 
       property :keepalive, [TrueClass, FalseClass],
-        description: "Determines whether or not HTTP/1.1 ``keep-alive`` should be used with this repository."
+        description: "Determines whether or not HTTP/1.1 `keep-alive` should be used with this repository."
 
       property :make_cache, [TrueClass, FalseClass],
         description: "Determines whether package files downloaded by Yum stay in cache directories. By using cached data, you can carry out certain operations without a network connection.",
         default: true
 
       property :max_retries, [String, Integer],
-        description: "Number of times any attempt to retrieve a file should retry before returning an error. Setting this to '0' makes Yum try forever."
+        description: "Number of times any attempt to retrieve a file should retry before returning an error. Setting this to `0` makes Yum try forever."
 
       property :metadata_expire, String, regex: [/^\d+$/, /^\d+[mhd]$/, /never/],
-               description: "Time (in seconds) after which the metadata will expire. If the current metadata downloaded is less than the value specified, then Yum will not update the metadata against the repository. If you find that Yum is not downloading information on updates as often as you would like lower the value of this option. You can also change from the default of using seconds to using days, hours or minutes by appending a 'd', 'h' or 'm' respectively. The default is six hours to compliment yum-updates running once per hour. It is also possible to use the word ``never``, meaning that the metadata will never expire. Note: When using a metalink file, the metalink must always be newer than the metadata for the repository due to the validation, so this timeout also applies to the metalink file.",
+               description: "Time (in seconds) after which the metadata will expire. If the current metadata downloaded is less than the value specified, then Yum will not update the metadata against the repository. If you find that Yum is not downloading information on updates as often as you would like lower the value of this option. You can also change from the default of using seconds to using days, hours or minutes by appending a 'd', 'h' or 'm' respectively. The default is six hours to compliment yum-updates running once per hour. It is also possible to use the word `never`, meaning that the metadata will never expire. Note: When using a metalink file, the metalink must always be newer than the metadata for the repository due to the validation, so this timeout also applies to the metalink file.",
                validation_message: "The metadata_expire property must be a numeric value for time in seconds, the string 'never', or a numeric value appended with with 'd', 'h', or 'm'!"
 
       property :metalink, String,
diff --git a/tasks/docs.rb b/tasks/docs.rb
index 46119b3664..d5fd653591 100755
--- a/tasks/docs.rb
+++ b/tasks/docs.rb
@@ -70,7 +70,7 @@ namespace :docs_site do
     def friendly_property_list(arr)
       return nil if arr.empty? # resources w/o properties
 
-      props = arr.map { |x| "``#{x["name"]}``" }
+      props = arr.map { |x| "`#{x["name"]}`" }
 
       # build the text string containing all properties bolded w/ punctuation
       if props.size > 1
@@ -153,19 +153,41 @@ namespace :docs_site do
       property["default"].to_s
     end
 
+    #
+    # Build the actions section of the resource yaml
+    #
+    # @return [Hash]
+    #
+    def action_list(actions)
+      list = {}
+      actions.sort.each do |action|
+        # skip it so we can make it the last value later
+        next if action == "nothing"
+
+        list[action.to_sym] = { "markdown" => nil }
+      end
+
+      # add the special case for nothing
+      list[:nothing] = { "shortcode" => "resources_common_actions_nothing.md" }
+
+      list
+    end
+
     # TODO:
     # - what to do about "lazy default" for default?
     def properties_list(properties)
       properties.map do |property|
-        {
-          "property" => property["name"],
-          "ruby_type" => friendly_types_list(property["is"]),
-          "required" => property["required"],
-          "default_value" =>  friendly_default_value(property),
-          # "allowed_values" => property["equal_to"].join(', '),
-          "new_in" => property["introduced"],
-          "description_list" => [{ "markdown" => property["description"] }],
-        }
+        default_val = friendly_default_value(property)
+
+        values = {}
+        values["property"] = property["name"]
+        values["ruby_type"] = friendly_types_list(property["is"])
+        values["required"] = property["required"]
+        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(', ')
+        values["description_list"] = [{ "markdown" => property["description"] }]
+        values
       end
     end
 
@@ -257,14 +279,12 @@ namespace :docs_site do
 
     # 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"] }
+      properties = data["properties"].reject { |v| v["name"] == "name" || v["deprecated"] }.sort_by! { |v| v["name"] }
 
       r = {}
 
-      # These properties are always set to these values.
+      # We want all our resources to show up in the main resource reference page
       r["resource_reference"] = true
-      r["robots"] = nil
-      r["syntax_code_block"] = nil
 
       # These properties are set to special values for only a few resources.
       r.merge!(special_properties(name, data))
@@ -279,7 +299,9 @@ namespace :docs_site do
       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["properties_list"] = properties_list(properties)
+      r["examples_list"] = nil
 
       r
     end
@@ -305,7 +327,9 @@ namespace :docs_site do
       else
         puts "Writing out #{resource}."
         FileUtils.mkdir_p "docs_site/#{resource}"
-        File.open("docs_site/#{resource}/_index.md", "w") { |f| f.write(resource_data.to_yaml) }
+        # write out the yaml contents of the hash and append a --- since this is actually a yaml
+        # block in the middle of a markdown page and the block needs an ending
+        File.open("docs_site/#{resource}/_index.md", "w") { |f| f.write(resource_data.to_yaml + "---") }
       end
     end
   end