summaryrefslogtreecommitdiff
path: root/tasks/docs.rb
blob: 325489321c8c2fb7e3785f70524f8a5f8efa3fb8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
RESOURCES_TO_SKIP = ["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", ""].freeze

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(__dir__, "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<Hash>
    # @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"] # right now we just want a boolean value here since the docs doesn't know what to do with an array of actions
        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)
      properties = {}

      # these package properties support passing arrays for the package name
      properties["common_resource_functionality_multiple_packages"] = true if %w{snap_package dpkg_package 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"] = "resource_log_properties.md" if name == "log"

      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))

      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 RESOURCES_TO_SKIP.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(YAML.dump(resource_data) + "---") }
      end
    end
  end
end