summaryrefslogtreecommitdiff
path: root/tasks
diff options
context:
space:
mode:
authorPete Higgins <pete@peterhiggins.org>2020-06-18 18:17:37 -0700
committerPete Higgins <pete@peterhiggins.org>2020-06-22 12:37:09 -0700
commitd84e7c6be3529055ebd5bb06a59e1339e6a9d4aa (patch)
tree1bb4d4d477b88f60a0320ac8451bd97dac1f4807 /tasks
parent99f17939d53c9254fa239d619a95583f66205dde (diff)
downloadchef-d84e7c6be3529055ebd5bb06a59e1339e6a9d4aa.tar.gz
Make the description parsing in docs rake task handle more stuff.
Signed-off-by: Pete Higgins <pete@peterhiggins.org>
Diffstat (limited to 'tasks')
-rwxr-xr-xtasks/docs.rb53
1 files changed, 33 insertions, 20 deletions
diff --git a/tasks/docs.rb b/tasks/docs.rb
index 954bfa6059..5ac6eeb3a6 100755
--- a/tasks/docs.rb
+++ b/tasks/docs.rb
@@ -112,20 +112,6 @@ namespace :docs_site do
fixed_arr.compact.join(", ")
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?
-
- description.split("Note: ")[1]
- end
-
- # Returns description without embedded notes that may be present
- def description_text(description)
- return nil if description.nil?
-
- description.split(" Note:")[0]
- end
-
# build the menu entry for this resource
def build_menu_item(name)
{
@@ -250,6 +236,38 @@ namespace :docs_site do
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"] }
@@ -266,12 +284,7 @@ namespace :docs_site do
r["resource"] = name
r["aliases"] = ["/resource_#{name}.html"]
r["menu"] = build_menu_item(name)
- r["resource_description_list"] = {}
- 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_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