diff options
Diffstat (limited to 'tasks/docs.rb')
| -rwxr-xr-x | tasks/docs.rb | 136 |
1 files changed, 59 insertions, 77 deletions
diff --git a/tasks/docs.rb b/tasks/docs.rb index cfa937c58d..f0aff0e32a 100755 --- a/tasks/docs.rb +++ b/tasks/docs.rb @@ -33,10 +33,12 @@ namespace :docs_site do 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(p["default"])}" unless pretty_default(p["default"]).nil? + 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" @@ -55,12 +57,16 @@ namespace :docs_site do 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.", - friendly_property_list(properties), ] + + # 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 @@ -83,8 +89,9 @@ namespace :docs_site do end # given an array of types print out a single comma separated string - # handling a nil value that needs to be printed as "nil" and TrueClass/FalseClass - # which needs to be "true" and "false" + # 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 (?) @@ -95,41 +102,28 @@ namespace :docs_site do "true" when "FalseClass" "false" - when "NilClass", nil - "nil" + when "NilClass" + nil else x end end + # compact to remove the nil values fixed_arr.compact.join(", ") end - # Makes sure the resource name is bolded within the description - # @return String - def bolded_description(name, description) - return nil if description.nil? # handle resources missing descriptions - - # 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 - + # split out notes from the description field. We didn't design a note syntax so we stick them in there def note_text(description) return nil if description.nil? - note = description.split("Note: ")[1] - if note - <<-HEREDOC + description.split("Note: ")[1] + end - .. note:: + # Returns description without embedded notes that may be present + def description_text(description) + return nil if description.nil? - #{note} - HEREDOC - end + description.split(" Note:")[0] end # build the menu entry for this resource @@ -180,7 +174,7 @@ namespace :docs_site do 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["allowed_values"] = property["equal_to"].join(", ") unless property["equal_to"].empty? values["description_list"] = [{ "markdown" => property["description"] }] values end @@ -189,85 +183,69 @@ namespace :docs_site do def special_properties(name, data) properties = {} - 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 + # 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}.include?(name) - properties["common_resource_functionality_resources_common_windows_security"] = name == "remote_directory" + properties["common_resource_functionality_resources_common_windows_security"] = true if name == "remote_directory" - properties["cookbook_file_specificity"] = name == "cookbook_file" + properties["cookbook_file_specificity"] = true if name == "cookbook_file" - properties["debug_recipes_chef_shell"] = name == "breakpoint" + properties["debug_recipes_chef_shell"] = true if name == "breakpoint" - properties["handler_custom"] = name == "chef_handler" + properties["handler_custom"] = true if name == "chef_handler" - properties["handler_types"] = name == "chef_handler" + properties["handler_types"] = true if name == "chef_handler" - properties["nameless_apt_update"] = name == "apt_update" + properties["nameless_apt_update"] = true if name == "apt_update" - properties["nameless_build_essential"] = name == "build_essential" + properties["nameless_build_essential"] = true if name == "build_essential" - properties["properties_multiple_packages"] = %w{dnf_package package zypper_package}.include?(name) + properties["properties_multiple_packages"] = true if %w{dnf_package package zypper_package}.include?(name) - properties["properties_resources_common_windows_security"] = %w{cookbook_file file template remote_file directory}.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 "breakpoint" - "resource_breakpoint_properties.md" when "ohai" "resource_ohai_properties.md" when "log" "resource_log_properties.md" - else - nil end - properties["ps_credential_helper"] = name == "dsc_script" + properties["ps_credential_helper"] = true if name == "dsc_script" - properties["registry_key"] = name == "registry_key" + properties["registry_key"] = true if name == "registry_key" - properties["remote_directory_recursive_directories"] = name == "remote_directory" + properties["remote_directory_recursive_directories"] = true if name == "remote_directory" - properties["remote_file_prevent_re_downloads"] = name == "remote_file" + properties["remote_file_prevent_re_downloads"] = true if name == "remote_file" - properties["remote_file_unc_path"] = name == "remote_file" + properties["remote_file_unc_path"] = true if name == "remote_file" - properties["resource_directory_recursive_directories"] = %w{directory remote_directory}.include?(name) + properties["resource_directory_recursive_directories"] = true if %w{directory remote_directory}.include?(name) - properties["resource_package_options"] = name == "package" + properties["resource_package_options"] = true if name == "package" - properties["resources_common_atomic_update"] = %w{cookbook_file file template remote_file}.include?(name) + properties["resources_common_atomic_update"] = true if %w{cookbook_file file template remote_file}.include?(name) - properties["resources_common_guard_interpreter"] = name == "script" + properties["resources_common_guard_interpreter"] = true if name == "script" - 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) + 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"] = !%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_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"] = !%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"] = name == "log" + properties["ruby_style_basics_chef_log"] = true if name == "log" - properties["syntax_shortcode"] = - case name - when "breakpoint" - "resource_breakpoint_syntax.md" - when "log" - "resource_log_syntax.md" - else - nil - end + properties["syntax_shortcode"] = "resource_log_syntax.md" if name == "log" - properties["template_requirements"] = name == "template" + properties["template_requirements"] = true if name == "template" - properties["unit_file_verification"] = name == "systemd_unit" + 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 @@ -289,8 +267,12 @@ namespace :docs_site do 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["resource_description_list"] = [{ "markdown" => description_text(data["description"]) }] + + # if the description contained a note then add it + r["resource_description_list"] << { "note" => { "markdown" => note_text(data["description"]) } } unless note_text(data["description"]).nil? + + 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) |