namespace :docs_site do desc "Generate resource documentation pages in a docs_site directory" task :resources do Encoding.default_external = Encoding::UTF_8 $:.unshift(File.expand_path(File.join(File.dirname(__FILE__), "lib"))) require "chef/resource_inspector" require "fileutils" require "yaml" # @return [String, nil] a pretty default value string or nil if we want to skip it def pretty_default(default) return nil if default.nil? || default == "" || default == "lazy default" if default.is_a?(String) # .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 # generate the top example resource block example text # @param properties Array # @return String 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 = "" text << "#{resource_name} 'name' do\n" properties.each do |p| pretty_default = pretty_default(p["default"]) 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}" unless pretty_default.nil? || (pretty_default.is_a?(String) && pretty_default.length > 45) # 45 chars is too long for these example blocks text << "\n" end text << " #{"action".ljust(padding_size)}Symbol # defaults to :#{default_action.first} if not specified\n" text << "end" text end # we need to know how much space to leave so columns line up # @return String def largest_property_name(properties) if properties.empty? 6 # we'll include "action" even without properties and it's 6 chars long else properties.max_by { |x| x["name"].size }["name"].size end end def friendly_full_property_list(name, properties) prop_list = [ "`#{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.", ] # handle the case where we have no properties prop_list << friendly_property_list(properties) unless properties.empty? prop_list end # given an array of properties print out a single comma separated string # handling commas and plural vs. singular wording depending # on the number of properties # @return String def friendly_property_list(arr) return nil if arr.empty? # resources w/o properties props = arr.map { |x| "`#{x["name"]}`" } # build the text string containing all properties bolded w/ punctuation if props.size > 1 props[-1] = "and #{props[-1]}" end text = props.size == 2 ? props.join(" ") : props.join(", ") text << ( props.size > 1 ? " are the properties" : " is the property" ) text << " available to this resource." text end # given an array of types print out a single comma separated string # handling TrueClass/FalseClass which needs to be "true" and "false" # and removing any nil values since those are less types in properties # and more side effects of legacy design # @return String # TODO: # - still does not include nil (?) def friendly_types_list(arr) fixed_arr = Array(arr).map do |x| case x when "TrueClass" "true" when "FalseClass" "false" when "NilClass" nil else x end end # compact to remove the nil values fixed_arr.compact.join(", ") end # 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 # print out the human readable form of the default def friendly_default_value(property) return "The resource block's name" if property["name_property"] return nil if property["default"].nil? || property["default"] == "" # this way we properly print out a string of a hash or an array instead of just the values 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| # nothing is a special case that sources the content from the docs site list[action.to_sym] = (action == "nothing" ? { "shortcode" => "resources_common_actions_nothing.md" } : { "markdown" => nil }) end list end # TODO: # - what to do about "lazy default" for default? def properties_list(properties) properties.map do |property| 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(", ") unless property["equal_to"].empty? values["description_list"] = [{ "markdown" => property["description"] }] values end end def special_properties(name, data) properties = {} # these package properties support passing arrays for the package name properties["common_resource_functionality_multiple_packages"] = true if %w{yum_package apt_package zypper_package homebrew_package dnf_package pacman_package homebrew_package}.include?(name) properties["common_resource_functionality_resources_common_windows_security"] = true if name == "remote_directory" properties["cookbook_file_specificity"] = true if name == "cookbook_file" properties["debug_recipes_chef_shell"] = true if name == "breakpoint" properties["handler_custom"] = true if name == "chef_handler" properties["handler_types"] = true if name == "chef_handler" properties["nameless_apt_update"] = true if name == "apt_update" properties["nameless_build_essential"] = true if name == "build_essential" properties["properties_multiple_packages"] = true if %w{dnf_package package zypper_package}.include?(name) properties["properties_resources_common_windows_security"] = true if %w{cookbook_file file template remote_file directory}.include?(name) properties["properties_shortcode"] = case name when "ohai" "resource_ohai_properties.md" when "log" "resource_log_properties.md" end properties["ps_credential_helper"] = true if name == "dsc_script" properties["registry_key"] = true if name == "registry_key" properties["remote_directory_recursive_directories"] = true if name == "remote_directory" properties["remote_file_prevent_re_downloads"] = true if name == "remote_file" properties["remote_file_unc_path"] = true if name == "remote_file" properties["resource_directory_recursive_directories"] = true if %w{directory remote_directory}.include?(name) properties["resource_package_options"] = true if name == "package" properties["resources_common_atomic_update"] = true if %w{cookbook_file file template remote_file}.include?(name) properties["resources_common_guard_interpreter"] = true if name == "script" properties["resources_common_guards"] = true unless %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) properties["resources_common_notification"] = true unless %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["resources_common_properties"] = true unless %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["ruby_style_basics_chef_log"] = true if name == "log" properties["syntax_shortcode"] = "resource_log_syntax.md" if name == "log" properties["template_requirements"] = true if name == "template" properties["unit_file_verification"] = true if name == "systemd_unit" # these packages all provide 'package' depending on OS and we want to inject a warning / note that you can just use 'package' instead properties["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 solaris_package windows_package yum_package zypper_package}.include?(name) properties end # Breaks a block of text into the different sections expected for the description, # 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(text) return [{ "markdown" => nil }] if text.nil? description_pattern = /(Note:|Warning:)?((?:(?!Note:|Warning:).)*)/m description = [] text.scan(description_pattern) do |preface, body| body.strip! next if body.empty? element = { "markdown" => body } case preface when "Note:" description << { "note" => element } when "Warning:" description << { "warning" => element } when nil description << element else raise "Unexpected thing happened! preface: '#{preface}', body: '#{body}'" end end description end # 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"] } r = {} # We want all our resources to show up in the main resource reference page r["resource_reference"] = true # 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"] = build_description(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["properties_list"] = properties_list(properties) r["examples"] = data["examples"] r end FileUtils.mkdir_p "docs_site" resources = Chef::JSONCompat.parse(ResourceInspector.inspect) 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) next if ENV["DEBUG"] && !(resource == ENV["DEBUG"]) resource_data = build_resource_data(resource, data) 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}" # 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 end