Merge pull request #9750 from chef/auto-generate-resource-docs

Updates for auto generated docs

8 files changed, 213 insertions, 254 deletions

diff --git a/lib/chef/resource/apt_preference.rb b/lib/chef/resource/apt_preference.rb
index 3432d2241e..9a661ce37d 100644
--- a/lib/chef/resource/apt_preference.rb
+++ b/lib/chef/resource/apt_preference.rb
@@ -43,7 +43,7 @@ class Chef
         required: true
 
       property :pin_priority, [String, Integer],
-        description: "Sets the Pin-Priority for a package.",
+        description: "Sets the Pin-Priority for a package. See <https://wiki.debian.org/AptPreferences> for more details.",
         required: true
 
       default_action :add
diff --git a/lib/chef/resource/apt_repository.rb b/lib/chef/resource/apt_repository.rb
index 75a30146ec..7e56a4b3af 100644
--- a/lib/chef/resource/apt_repository.rb
+++ b/lib/chef/resource/apt_repository.rb
@@ -115,8 +115,8 @@ class Chef
         description: "The base of the Debian distribution."
 
       property :distribution, [ String, nil, FalseClass ],
-        description: "Usually a distribution's codename, such as trusty, xenial or bionic. Default value: the codename of the node's distro.",
-        default: lazy { node["lsb"]["codename"] }, default_description: "The LSB codename of the host such as 'bionic'."
+        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'.",
@@ -142,7 +142,7 @@ class Chef
         default: lazy { [] }, coerce: proc { |x| x ? Array(x) : x }
 
       property :key_proxy, [String, nil, FalseClass],
-        description: "If set, a specified proxy is passed to GPG via http-proxy=."
+        description: "If set, a specified proxy is passed to GPG via `http-proxy=`."
 
       property :cookbook, [String, nil, FalseClass],
         description: "If key should be a cookbook_file, specify a cookbook where the key is located for files/default. Default value is nil, so it will use the cookbook where the resource is used.",
diff --git a/lib/chef/resource/chef_client_cron.rb b/lib/chef/resource/chef_client_cron.rb
index 99207a28be..7f4b036b88 100644
--- a/lib/chef/resource/chef_client_cron.rb
+++ b/lib/chef/resource/chef_client_cron.rb
@@ -103,7 +103,7 @@ class Chef
         description: "The e-mail address to e-mail any cron task failures to."
 
       property :accept_chef_license, [true, false],
-        description: "Accept the Chef Online Master License and Services Agreement. See https://www.chef.io/online-master-agreement/",
+        description: "Accept the Chef Online Master License and Services Agreement. See <https://www.chef.io/online-master-agreement/>",
         default: false
 
       property :config_directory, String,
@@ -112,6 +112,7 @@ class Chef
 
       property :log_directory, String,
         default: lazy { platform?("mac_os_x") ? "/Library/Logs/#{Chef::Dist::DIR_SUFFIX.capitalize}" : "/var/log/#{Chef::Dist::DIR_SUFFIX}" },
+        default_description: "/Library/Logs/#{Chef::Dist::DIR_SUFFIX.capitalize} on macOS and /var/log/#{Chef::Dist::DIR_SUFFIX} otherwise",
         description: "The path of the directory to create the log file in."
 
       property :log_file_name, String,
diff --git a/lib/chef/resource/chef_client_scheduled_task.rb b/lib/chef/resource/chef_client_scheduled_task.rb
index 1e500b4aa7..2479e5bc5a 100644
--- a/lib/chef/resource/chef_client_scheduled_task.rb
+++ b/lib/chef/resource/chef_client_scheduled_task.rb
@@ -72,7 +72,7 @@ class Chef
         default: 30
 
       property :accept_chef_license, [true, false],
-        description: "Accept the Chef Online Master License and Services Agreement. See https://www.chef.io/online-master-agreement/",
+        description: "Accept the Chef Online Master License and Services Agreement. See <https://www.chef.io/online-master-agreement/>",
         default: false
 
       property :start_date, String,
@@ -99,7 +99,8 @@ class Chef
 
       property :log_directory, String,
         description: "The path of the directory to create the log file in.",
-        default: lazy { |r| "#{r.config_directory}/log" }
+        default: lazy { |r| "#{r.config_directory}/log" },
+        default_description: "CONFIG_DIRECTORY/log"
 
       property :log_file_name, String,
         description: "The name of the log file to use.",
diff --git a/lib/chef/resource/chef_client_systemd_timer.rb b/lib/chef/resource/chef_client_systemd_timer.rb
index 9b16057c89..a1d26758de 100644
--- a/lib/chef/resource/chef_client_systemd_timer.rb
+++ b/lib/chef/resource/chef_client_systemd_timer.rb
@@ -72,7 +72,7 @@ class Chef
         default: "5min"
 
       property :accept_chef_license, [true, false],
-        description: "Accept the Chef Online Master License and Services Agreement. See https://www.chef.io/online-master-agreement/",
+        description: "Accept the Chef Online Master License and Services Agreement. See <https://www.chef.io/online-master-agreement/>",
         default: false
 
       property :run_on_battery, [true, false],
diff --git a/lib/chef/resource/windows_firewall_rule.rb b/lib/chef/resource/windows_firewall_rule.rb
index fcba0dc569..0ba4c60a46 100644
--- a/lib/chef/resource/windows_firewall_rule.rb
+++ b/lib/chef/resource/windows_firewall_rule.rb
@@ -26,7 +26,7 @@ class Chef
     class WindowsFirewallRule < Chef::Resource
       provides :windows_firewall_rule
 
-      description "Use the windows_firewall_rule resource to create, change or remove windows firewall rules."
+      description "Use the windows_firewall_rule resource to create, change or remove Windows firewall rules."
       introduced "14.7"
       examples <<~DOC
       Allowing port 80 access
diff --git a/lib/chef/resource/windows_service.rb b/lib/chef/resource/windows_service.rb
index 34f3cfb9a7..3c9a63b86e 100644
--- a/lib/chef/resource/windows_service.rb
+++ b/lib/chef/resource/windows_service.rb
@@ -46,41 +46,47 @@ class Chef
         default: 60,
         desired_state: false
 
-      # The display name to be used by user interface programs to identify the
-      # service. This string has a maximum length of 256 characters.
       property :display_name, String, regex: /^.{1,256}$/,
-               validation_message: "The display_name can only be a maximum of 256 characters!",
-               introduced: "14.0"
+        description: "The display name to be used by user interface programs to identify the service. This string has a maximum length of 256 characters.",
+        validation_message: "The display_name can only be a maximum of 256 characters!",
+        introduced: "14.0"
 
       # https://github.com/chef/win32-service/blob/ffi/lib/win32/windows/constants.rb#L19-L29
-      property :desired_access, Integer, default: SERVICE_ALL_ACCESS
+      property :desired_access, Integer,
+        default: SERVICE_ALL_ACCESS,
+        introduced: "14.0"
 
       # https://github.com/chef/win32-service/blob/ffi/lib/win32/windows/constants.rb#L31-L41
-      property :service_type, Integer, default: SERVICE_WIN32_OWN_PROCESS
+      property :service_type, Integer, default: SERVICE_WIN32_OWN_PROCESS,
+      introduced: "14.0"
 
       # Valid options:
       #   - :automatic
       #   - :manual
       #   - :disabled
       # Reference: https://github.com/chef/win32-service/blob/ffi/lib/win32/windows/constants.rb#L49-L54
-      property :startup_type, [Symbol], equal_to: %i{automatic manual disabled}, default: :automatic, coerce: proc { |x|
-        if x.is_a?(Integer)
-          ALLOWED_START_TYPES.invert.fetch(x) do
-            Chef::Log.warn("Unsupported startup_type #{x}, falling back to :automatic")
-            :automatic
+      property :startup_type, [Symbol],
+        equal_to: %i{automatic manual disabled},
+        default: :automatic,
+        description: "Use to specify the startup type of the service.",
+        coerce: proc { |x|
+          if x.is_a?(Integer)
+            ALLOWED_START_TYPES.invert.fetch(x) do
+              Chef::Log.warn("Unsupported startup_type #{x}, falling back to :automatic")
+              :automatic
+            end
+          elsif x.is_a?(String)
+            x.to_sym
+          else
+            x
           end
-        elsif x.is_a?(String)
-          x.to_sym
-        else
-          x
-        end
-      }
-
-      # This only applies if startup_type is :automatic
+        }
+
       # 1 == delayed start is enabled
       # 0 == NO delayed start
       property :delayed_start, [TrueClass, FalseClass],
         introduced: "14.0",
+        description: "Set the startup type to delayed start. This only applies if `startup_type` is `:automatic`",
         default: false, coerce: proc { |x|
           if x.is_a?(Integer)
             x == 0 ? false : true
@@ -90,31 +96,34 @@ class Chef
         }
 
       # https://github.com/chef/win32-service/blob/ffi/lib/win32/windows/constants.rb#L43-L47
-      property :error_control, Integer, default: SERVICE_ERROR_NORMAL
+      property :error_control, Integer,
+        default: SERVICE_ERROR_NORMAL,
+        introduced: "14.0"
 
       property :binary_path_name, String,
         introduced: "14.0",
-        description: "The fully qualified path to the service binary file. The path can also include arguments for an auto-start service. This is required for ':create' and ':configure' actions"
+        description: "The fully qualified path to the service binary file. The path can also include arguments for an auto-start service. This is required for `:create` and `:configure` actions"
 
       property :load_order_group, String,
         introduced: "14.0",
-        description: "The names of the load ordering group of which this service is a member. Don't set this property if the service does not belong to a group."
-
-      # A pointer to a double null-terminated array of null-separated names of
-      # services or load ordering groups that the system must start before this
-      # service. Specify nil or an empty string if the service has no
-      # dependencies. Dependency on a group means that this service can run if
-      # at least one member of the group is running after an attempt to start
-      # all members of the group.
+        description: "The name of the service's load ordering group(s)."
+
       property :dependencies, [String, Array],
+        description: "A pointer to a double null-terminated array of null-separated names of services or load ordering groups that the system must start before this service. Specify `nil` or an empty string if the service has no dependencies. Dependency on a group means that this service can run if at least one member of the group is running after an attempt to start all members of the group.",
         introduced: "14.0"
 
       property :description, String,
         description: "Description of the service.",
         introduced: "14.0"
 
-      property :run_as_user, String, default: "localsystem", coerce: proc { |x| x.downcase }
-      property :run_as_password, String, default: ""
+      property :run_as_user, String,
+        description: "The user under which a Microsoft Windows service runs.",
+        default: "localsystem",
+        coerce: proc { |x| x.downcase }
+
+      property :run_as_password, String,
+        description: "The password for the user specified by `run_as_user`.",
+        default: ""
     end
   end
 end
diff --git a/tasks/docs.rb b/tasks/docs.rb
index c347445c2e..c4d6d5a07a 100755
--- a/tasks/docs.rb
+++ b/tasks/docs.rb
@@ -1,6 +1,6 @@
 namespace :docs_site do
 
-  desc "Generate resource documentation .rst pages in a docs_site directory"
+  desc "Generate resource documentation pages in a docs_site directory"
 
   task :resources do
     Encoding.default_external = Encoding::UTF_8
@@ -8,16 +8,8 @@ namespace :docs_site do
     $:.unshift(File.expand_path(File.join(File.dirname(__FILE__), "lib")))
 
     require "chef/resource_inspector"
-    require "erb"
     require "fileutils"
-
-    # @param version String
-    # @return String Chef Infra Client or Chef Client depending on version
-    def branded_chef_client_name(version)
-      return "Chef Infra Client" if Gem::Version.new(version) >= Gem::Version.new("15")
-
-      "Chef Client"
-    end
+    require "yaml"
 
     # @return [String, nil] a pretty defaul value string or nil if we want to skip it
     def pretty_default(default)
@@ -34,20 +26,21 @@ namespace :docs_site do
     # generate the top example resource block example text
     # @param properties Array<Hash>
     # @return String
-    def generate_resource_block(resource_name, properties)
+    def generate_resource_block(resource_name, properties, default_action)
       padding_size = largest_property_name(properties) + 6
 
       # build the resource string with property spacing between property names and comments
-      text = "  #{resource_name} 'name' do\n"
+      text = ""
+      text << "#{resource_name} 'name' do\n"
       properties.each do |p|
-        text << "    #{p["name"].ljust(padding_size)}"
+        text << "  #{p["name"].ljust(padding_size)}"
         text << friendly_types_list(p["is"])
         text << " # default value: 'name' unless specified" if p["name_property"]
         text << " # default value: #{pretty_default(p["default"])}" unless pretty_default(p["default"]).nil?
         text << "\n"
       end
-      text << "    #{"action".ljust(padding_size)}Symbol # defaults to :#{@default_action.first} if not specified\n"
-      text << "  end"
+      text << "  #{"action".ljust(padding_size)}Symbol # defaults to :#{default_action.first} if not specified\n"
+      text << "end"
       text
     end
 
@@ -61,11 +54,20 @@ namespace :docs_site do
       end
     end
 
+    def friendly_full_property_list(name, properties)
+      [
+        "`#{name}` is the resource.",
+        "`name` is the name given to the resource block.",
+        "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state.",
+        friendly_property_list(properties),
+      ]
+    end
+
     # given an array of properties print out a single comma separated string
-    # handling commas / and properly and plural vs. singular wording depending
+    # handling commas and plural vs. singular wording depending
     # on the number of properties
     # @return String
-    def friendly_properly_list(arr)
+    def friendly_property_list(arr)
       return nil if arr.empty? # resources w/o properties
 
       props = arr.map { |x| "``#{x["name"]}``" }
@@ -84,6 +86,8 @@ namespace :docs_site do
     # handling a nil value that needs to be printed as "nil" and TrueClass/FalseClass
     # which needs to be "true" and "false"
     # @return String
+    # TODO:
+    # - still does not include nil (?)
     def friendly_types_list(arr)
       fixed_arr = Array(arr).map do |x|
         case x
@@ -91,6 +95,8 @@ namespace :docs_site do
           "true"
         when "FalseClass"
           "false"
+        when "NilClass", nil
+          "nil"
         else
           x
         end
@@ -126,243 +132,185 @@ namespace :docs_site do
       end
     end
 
-    def boilerplate_content
-      <<~HEREDOC
-        Common Resource Functionality
-        =====================================================
-
-        Chef resources include common properties, notifications, and resource guards.
-
-        Common Properties
-        -----------------------------------------------------
-
-        .. tag resources_common_properties
-
-        The following properties are common to every resource:
-
-        ``ignore_failure``
-          **Ruby Type:** true, false | **Default Value:** ``false``
-
-          Continue running a recipe if a resource fails for any reason.
-
-        ``retries``
-          **Ruby Type:** Integer | **Default Value:** ``0``
-
-          The number of attempts to catch exceptions and retry the resource.
-
-        ``retry_delay``
-          **Ruby Type:** Integer | **Default Value:** ``2``
-
-          The retry delay (in seconds).
-
-        ``sensitive``
-          **Ruby Type:** true, false | **Default Value:** ``false``
-
-          Ensure that sensitive resource data is not logged by Chef Infra Client.
-
-        .. end_tag
-
-        Notifications
-        -----------------------------------------------------
-
-        ``notifies``
-          **Ruby Type:** Symbol, 'Chef::Resource[String]'
-
-          .. tag resources_common_notification_notifies
-
-          A resource may notify another resource to take action when its state changes. Specify a ``'resource[name]'``, the ``:action`` that resource should take, and then the ``:timer`` for that action. A resource may notify more than one resource; use a ``notifies`` statement for each resource to be notified.
-
-          .. end_tag
-
-        .. tag resources_common_notification_timers
-
-        A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
-
-        ``:before``
-           Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
-
-        ``:delayed``
-           Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
-
-        ``:immediate``, ``:immediately``
-           Specifies that a notification should be run immediately, per resource notified.
-
-        .. end_tag
-
-        .. tag resources_common_notification_notifies_syntax
-
-        The syntax for ``notifies`` is:
-
-        .. code-block:: ruby
-
-          notifies :action, 'resource[name]', :timer
+    # build the menu entry for this resource
+    def build_menu_item(name)
+      {
+        "infra" => {
+          "title" => name,
+          "identifier" => "chef_infra/cookbook_reference/resources/#{name} #{name}",
+          "parent" => "chef_infra/cookbook_reference/resources",
+        },
+      }
+    end
 
-        .. end_tag
+    # print out the human readable form of the default
+    def friendly_default_value(property)
+      return "The resource block's name" if property["name_property"]
 
-        ``subscribes``
-          **Ruby Type:** Symbol, 'Chef::Resource[String]'
+      return nil if property["default"].nil?
 
-        .. tag resources_common_notification_subscribes
+      # this way we properly print out a string of a hash or an array instead of just the values
+      property["default"].to_s
+    end
 
-        A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a ``'resource[name]'``, the ``:action`` to be taken, and then the ``:timer`` for that action.
+    # TODO:
+    # - what to do about "lazy default" for default?
+    def properties_list(properties)
+      properties.map do |property|
+        if property["deprecated"] # we don't want to document deprecated properties
+          nil
+        else
+          {
+            "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"] }],
+          }
+        end
+      end
+    end
 
-        Note that ``subscribes`` does not apply the specified action to the resource that it listens to - for example:
+    def special_properties(name, data)
+      properties = {}
 
-        .. code-block:: ruby
+      properties["common_resource_functionality_multiple_packages"] =
+        case name
+        when "yum_package", "apt_package", "zypper_package", "homebrew_package", "dnf_package", "pacman_package"
+          true
+        when "package"
+          nil
+        else
+          false
+        end
 
-         file '/etc/nginx/ssl/example.crt' do
-           mode '0600'
-           owner 'root'
-         end
+      properties["common_resource_functionality_resources_common_windows_security"] = name == "remote_directory"
 
-         service 'nginx' do
-           subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
-         end
+      properties["cookbook_file_specificity"] = name == "cookbook_file"
 
-        In this case the ``subscribes`` property reloads the ``nginx`` service whenever its certificate file, located under ``/etc/nginx/ssl/example.crt``, is updated. ``subscribes`` does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the ``:reload`` action for its resource (in this example ``nginx``) when a change is detected.
+      properties["debug_recipes_chef_shell"] = name == "breakpoint"
 
-        .. end_tag
+      properties["handler_custom"] = name == "chef_handler"
 
-        .. tag resources_common_notification_timers
+      properties["handler_types"] = name == "chef_handler"
 
-        A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
+      properties["nameless_apt_update"] = name == "apt_update"
 
-        ``:before``
-           Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
+      properties["nameless_build_essential"] = name == "build_essential"
 
-        ``:delayed``
-           Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
+      properties["properties_multiple_packages"] = %w{dnf_package package zypper_package}.include?(name)
 
-        ``:immediate``, ``:immediately``
-           Specifies that a notification should be run immediately, per resource notified.
+      properties["properties_resources_common_windows_security"] = %w{cookbook_file file template remote_file directory}.include?(name)
 
-        .. end_tag
+      properties["properties_shortcode"] =
+        case name
+        when "breakpoint"
+          "resource_breakpoint_properties.md"
+        when "ohai"
+          "resource_ohai_properties.md"
+        when "log"
+          "resource_log_properties.md"
+        else
+          nil
+        end
 
-        .. tag resources_common_notification_subscribes_syntax
+      properties["ps_credential_helper"] = name == "dsc_script"
 
-        The syntax for ``subscribes`` is:
+      properties["registry_key"] = name == "registry_key"
 
-        .. code-block:: ruby
+      properties["remote_directory_recursive_directories"] = name == "remote_directory"
 
-           subscribes :action, 'resource[name]', :timer
+      properties["remote_file_prevent_re_downloads"] = name == "remote_file"
 
-        .. end_tag
+      properties["remote_file_unc_path"] = name == "remote_file"
 
-        Guards
-        -----------------------------------------------------
+      properties["resource_directory_recursive_directories"] = %w{directory remote_directory}.include?(name)
 
-        .. tag resources_common_guards
+      properties["resource_package_options"] = name == "package"
 
-        A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
+      properties["resources_common_atomic_update"] = %w{cookbook_file file template remote_file}.include?(name)
 
-        * A string is executed as a shell command. If the command returns ``0``, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a **powershell_script** run Windows PowerShell commands and may return ``true`` in addition to ``0``.
-        * A block is executed as Ruby code that must return either ``true`` or ``false``. If the block returns ``true``, the guard property is applied. If the block returns ``false``, the guard property is not applied.
+      properties["resources_common_guard_interpreter"] = name == "script"
 
-        A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
+      properties["resources_common_guards"] = !%w{ruby_block chef_acl chef_environment chef_data_bag chef_mirror chef_container chef_client chef_organization remote_file chef_node chef_group breakpoint chef_role registry_key chef_data_bag_item chef_user package}.include?(name)
 
-        .. end_tag
+      properties["resources_common_notification"] = !%w{ruby_block chef_acl python chef_environment chef_data_bag chef_mirror perl chef_container chef_client chef_organization remote_file chef_node chef_group breakpoint chef_role registry_key chef_data_bag_item chef_user ruby package}.include?(name)
 
-        **Properties**
+      properties["resources_common_properties"] = !%w{ruby_block chef_acl python chef_environment chef_data_bag chef_mirror perl chef_container chef_client chef_organization remote_file chef_node chef_group breakpoint chef_role registry_key chef_data_bag_item chef_user ruby package}.include?(name)
 
-        .. tag resources_common_guards_properties
+      properties["ruby_style_basics_chef_log"] = name == "log"
 
-        The following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
+      properties["syntax_shortcode"] =
+        case name
+        when "breakpoint"
+          "resource_breakpoint_syntax.md"
+        when "log"
+          "resource_log_syntax.md"
+        else
+          nil
+        end
 
-        ``not_if``
-          Prevent a resource from executing when the condition returns ``true``.
+      properties["template_requirements"] = name == "template"
 
-        ``only_if``
-          Allow a resource to execute only if the condition returns ``true``.
+      properties["unit_file_verification"] = name == "systemd_unit"
 
-        .. end_tag
-      HEREDOC
+      properties
     end
 
-    template = %{=====================================================
-<%= @name %> resource
-=====================================================
-`[edit on GitHub] <https://github.com/chef/chef-web-docs/blob/master/chef_master/source/resource_<%= @name %>.rst>`__
-
-<%= bolded_description(@name, @description) %>
-<%= note_text(@description) -%>
-<% unless @introduced.nil? -%>
-
-**New in <%= branded_chef_client_name(@introduced) %> <%= @introduced %>.**
-<% end -%>
-
-Syntax
-=====================================================
-
-The <%= @name %> resource has the following syntax:
-
-.. code-block:: ruby
-
-<%= @resource_block %>
-
-where:
-
-* ``<%= @name %>`` is the resource.
-* ``name`` is the name given to the resource block.
-* ``action`` identifies which steps Chef Infra Client will take to bring the node into the desired state.
-<% unless @property_list.nil? %>* <%= @property_list %><% end %>
-
-Actions
-=====================================================
-
-The <%= @name %> resource has the following actions:
-<% @actions.each do |a| %>
-``:<%= a %>``
-   <% if a == @default_action %>Default. <% end %>Description here.
-<% end %>
-``:nothing``
-   .. tag resources_common_actions_nothing
-
-   This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
-
-   .. end_tag
-
-Properties
-=====================================================
+    # 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" }.sort_by! { |v| v["name"] }
+
+      r = {}
+
+      # These properties are always set to these values.
+      r["draft"] = false
+      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))
+
+      r["title"] = "#{name} resource"
+      r["resource"] = name
+      r["aliases"] = ["/resource_#{name}.html"]
+      r["menu"] = build_menu_item(name)
+      r["resource_description_list"] = {}
+      r["resource_description_list"] = [{ "markdown" => data["description"] }]
+      r["resource_new_in"] = data["introduced"]
+      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["properties_list"] = properties_list(properties)
+
+      r
+    end
 
-The <%= @name %> resource has the following properties:
-<% @properties.each do |p| %>
-``<%= p['name'] %>``
-   **Ruby Type:** <%= friendly_types_list(p['is']) %><% unless pretty_default(p['default']).nil? %> | **Default Value:** ``<%= pretty_default(p['default']) %>``<% end %><% if p['required'] %> | ``REQUIRED``<% end %><% if p['deprecated'] %> | ``DEPRECATED``<% end %><% if p['name_property'] %> | **Default Value:** ``The resource block's name``<% end %>
+    FileUtils.mkdir_p "docs_site"
+    resources = Chef::JSONCompat.parse(ResourceInspector.inspect)
 
-<% unless p['description'].nil? %>   <%= p['description'].strip %><% end %>
-<% unless p['introduced'].nil? -%>\n\n   *New in <%= branded_chef_client_name(p['introduced']) %> <%= p['introduced'] -%>.*\n<% end -%>
-<% end %>
-<% if @properties.empty? %>This resource does not have any properties.\n<% end -%>
-<%= boilerplate_content %>
-Examples
-=====================================================
+    resources.each do |resource, data|
+      # skip some resources we don't directly document
+      next if ["whyrun_safe_ruby_block", "l_w_r_p_base", "user_resource_abstract_base_class", "linux_user", "pw_user", "aix_user", "dscl_user", "solaris_user", "windows_user", "mac_user", ""].include?(resource)
 
-The following examples demonstrate various approaches for using resources in recipes:
+      next if ENV["DEBUG"] && !(resource == ENV["DEBUG"])
 
-<%= @examples -%>
-}
+      resource_data = build_resource_data(resource, data)
 
-    FileUtils.mkdir_p "docs_site"
-    resources = Chef::JSONCompat.parse(ResourceInspector.inspect)
-    resources.each do |resource, data|
-      next if ["scm", "whyrun_safe_ruby_block", "l_w_r_p_base", "user_resource_abstract_base_class", "linux_user", "pw_user", "aix_user", "dscl_user", "solaris_user", "windows_user", ""].include?(resource)
-
-      puts "Writing out #{resource}."
-      @name = resource
-      @description = data["description"]
-      @default_action = data["default_action"]
-      @actions = (data["actions"] - ["nothing"]).sort
-      @examples = data["examples"]
-      @introduced = data["introduced"]
-      @preview = data["preview"]
-      @properties = data["properties"].reject { |v| v["name"] == "name" }.sort_by! { |v| v["name"] }
-      @resource_block = generate_resource_block(resource, @properties)
-      @property_list = friendly_properly_list(@properties)
-      @examples = data["examples"]
-
-      t = ERB.new(template, nil, "-")
-      File.open("docs_site/resource_#{@name}.rst", "w") do |f|
-        f.write t.result(binding)
+      if ENV["DEBUG"]
+        require "pp"
+        pp resource
+        puts "=========="
+        pp data
+        puts "=========="
+        pp resource_data
+      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) }
       end
     end
   end