Expand delimiters if code contains backticks

lib/puppet-strings/markdown/helpers.rb

@@ -4,18 +4,28 @@
 module PuppetStrings::Markdown::Helpers
   # Formats code as either inline or a block.
   #
-  # Note that this does not do any escaping even if the code contains ` or ```.
+  # Delimiters are expanded if the code contains the default delimiter.
   #
   # @param [String] code The code to format.
   # @param [Symbol] type The type of the code, e.g. :text, :puppet, or :ruby.
-  # @param [String] block_prefix String to insert before if it’s a block.
-  # @param [String] inline_prefix String to insert before if it’s inline.
+  # @param [String] block_prefix String to insert before if it's a block.
+  # @param [String] inline_prefix String to insert before if it's inline.
+  # @param [Symbol] whether to force a format (:inline, :block) or determine by content (:none).
   # @returns [String] Markdown
-  def code_maybe_block(code, type: :puppet, block_prefix: "\n\n", inline_prefix: ' ')
-    if code.to_s.include?("\n")
-      "#{block_prefix}```#{type}\n#{code}\n```"
+  def code_maybe_block(code, type: :puppet, block_prefix: "\n\n", inline_prefix: ' ', force: :none)
+    code_s = code.to_s
+    if (code_s.include?("\n") || code_s.length > 70 || force == :block) && force != :inline
+      # Delimiter must be one backtick longer than the longest series of backticks
+      #   beginning a line, minimum 3 (with some spaces allowed).
+      delim = (code_s.scan(/^ {0,3}``(`+)\s*$/) << '').flatten.max_by(&:length) + '```'
+      "#{block_prefix}#{delim}#{type}\n#{code_s}\n#{delim}"
     else
-      "#{inline_prefix}`#{code}`"
+      # Delimeter must be one backtick longer than the longest series of backticks
+      #   in the string.
+      delim = code_s.scan(/`*/).max_by(&:length) + '`'
+      # Padding required if string starts or ends with a backtick
+      pad = (code_s[0] == '`' || code_s[-1] == '`') ? ' ' : ''
+      "#{inline_prefix}#{delim}#{pad}#{code_s}#{pad}#{delim}"
     end
   end
 end

lib/puppet-strings/markdown/templates/classes_and_defines.erb

@@ -42,9 +42,7 @@
 <% examples.each do |eg| -%>
 ##### <%= eg[:name] %>
 
-```puppet
-<%= eg[:text] %>
-```
+<%= code_maybe_block(eg[:text], block_prefix: '', force: :block) %>
 
 <% end -%>
 <% end -%>
@@ -71,7 +69,7 @@ Options:
 
 <% options_for_param(param[:name]).each do |o| -%>
 <% if o[:opt_types] -%>
-* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+* **<%= o[:opt_name] %>**<%= code_maybe_block(o[:opt_types][0], force: :inline) %>: <%= o[:opt_text] %>
 <% else -%>
 * **<%= o[:opt_name] %>**: <%= o[:opt_text] %>
 <% end -%>

lib/puppet-strings/markdown/templates/data_type.erb

@@ -42,9 +42,7 @@
 <% examples.each do |eg| -%>
 ##### <%= eg[:name] %>
 
-```puppet
-<%= eg[:text] %>
-```
+<%= code_maybe_block(eg[:text], block_prefix: '', force: :block) %>
 
 <% end -%>
 <% end -%>
@@ -74,7 +72,7 @@ Data type:<%= code_maybe_block(param[:types].join(', ')) %>
 Options:
 
 <% options_for_param(param[:name]).each do |o| -%>
-* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+* **<%= o[:opt_name] %>**<%= code_maybe_block(o[:opt_types][0], force: :inline) %>: <%= o[:opt_text] %>
 <% end -%>
 
 <% end -%>

lib/puppet-strings/markdown/templates/data_type_function.erb

@@ -1,6 +1,6 @@
 ### <a name="<%= link %>"></a>`<%= name %>`
 
-#### `<%= signature %>`
+####<%= code_maybe_block(signature, force: :inline) %>
 
 <% if text -%>
 <%= text %>
@@ -17,7 +17,7 @@
 
 <% end -%>
 <% if return_type -%>
-Returns: `<%= return_type %>`<% if return_val %> <%= return_val %><% end %>
+Returns:<%= code_maybe_block(return_type, force: :inline) %><% if return_val %> <%= return_val %><% end %>
 
 <% end -%>
 <% if raises -%>
@@ -33,9 +33,7 @@ Raises:
 <% examples.each do |eg| -%>
 ###### <%= eg[:name] %>
 
-```puppet
-<%= eg[:text] %>
-```
+<%= code_maybe_block(eg[:text], block_prefix: '', force: :block) %>
 
 <% end -%>
 <% end -%>
@@ -51,7 +49,7 @@ Data type:<%= code_maybe_block(param[:types][0]) %>
 Options:
 
 <% options_for_param(param[:name]).each do |o| -%>
-* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+* **<%= o[:opt_name] %>**<%= code_maybe_block(o[:opt_types][0], force: :inline) %>: <%= o[:opt_text] %>
 <% end -%>
 
 <% end -%>

lib/puppet-strings/markdown/templates/function.erb

@@ -30,14 +30,12 @@ Type: <%= type %>
 <% examples.each do |eg| -%>
 ##### <%= eg[:name] %>
 
-```puppet
-<%= eg[:text] %>
-```
+<%= code_maybe_block(eg[:text], block_prefix: '', force: :block) %>
 
 <% end -%>
 <% end -%>
 <% signatures.each do |sig| -%>
-#### `<%= sig.signature %>`
+####<%= code_maybe_block(sig.signature, force: :inline) %>
 
 <% if sig.text -%>
 <%= sig.text %>
@@ -54,7 +52,7 @@ Type: <%= type %>
 
 <% end -%>
 <% if sig.return_type -%>
-Returns: `<%= sig.return_type %>`<% if sig.return_val %> <%= sig.return_val %><% end %>
+Returns:<%= code_maybe_block(sig.return_type, force: :inline) %><% if sig.return_val %> <%= sig.return_val %><% end %>
 
 <% end -%>
 <% if raises -%>
@@ -71,9 +69,7 @@ Raises:
 <% sig.examples.each do |eg| -%>
 ###### <%= eg[:name] %>
 
-```puppet
-<%= eg[:text] %>
-```
+<%= code_maybe_block(eg[:text], block_prefix: '', force: :block) %>
 
 <% end -%>
 <% end -%>
@@ -89,7 +85,7 @@ Data type:<%= code_maybe_block(param[:types][0]) %>
 Options:
 
 <% sig.options_for_param(param[:name]).each do |o| -%>
-* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+* **<%= o[:opt_name] %>**<%= code_maybe_block(o[:opt_types][0], force: :inline) %>: <%= o[:opt_text] %>
 <% end -%>
 
 <% end -%>

lib/puppet-strings/markdown/templates/resource_type.erb

@@ -42,9 +42,7 @@
 <% examples.each do |eg| -%>
 ##### <%= eg[:name] %>
 
-```puppet
-<%= eg[:text] %>
-```
+<%= code_maybe_block(eg[:text], block_prefix: '', force: :block) %>
 
 <% end -%>
 <% end -%>
@@ -69,7 +67,7 @@ Aliases: `<%= prop[:aliases].to_s.delete('{').delete('}') %>`
 
 <% end -%>
 <% if prop[:data_type] -%>
-Data type: `<%= prop[:data_type] %>`<%= "\n_\*this data type contains a regex that may not be accurately reflected in generated documentation_" if regex_in_data_type?(prop[:data_type]) %>
+Data type:<%= code_maybe_block(prop[:data_type]) %>
 
 <% end -%>
 <%= prop[:description] %>
@@ -78,7 +76,7 @@ Data type: `<%= prop[:data_type] %>`<%= "\n_\*this data type contains a regex th
 Options:
 
 <% options_for_param(prop[:name]).each do |o| -%>
-* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+* **<%= o[:opt_name] %>**<%= code_maybe_block(o[:opt_types][0], force: :inline) %>: <%= o[:opt_text] %>
 <% end -%>
 
 <% end -%>
@@ -121,7 +119,7 @@ Aliases: `<%= param[:aliases].to_s.delete('{').delete('}') %>`
 
 <% end -%>
 <% if param[:data_type] -%>
-Data type: `<%= param[:data_type] %>`<%= "\n_\*this data type contains a regex that may not be accurately reflected in generated documentation_" if regex_in_data_type?(param[:data_type]) %>
+Data type:<%= code_maybe_block(param[:data_type]) %>
 
 <% end -%>
 <% if param[:description] -%>
@@ -132,7 +130,7 @@ Data type: `<%= param[:data_type] %>`<%= "\n_\*this data type contains a regex t
 Options:
 
 <% options_for_param(param[:name]).each do |o| -%>
-* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+* **<%= o[:opt_name] %>**<%= code_maybe_block(o[:opt_types][0], force: :inline) %>: <%= o[:opt_text] %>
 <% end -%>
 
 <% end -%>
@@ -145,7 +143,7 @@ Options:
 
 <% end -%>
 <% if param[:default] -%>
-Default value: `<%= param[:default] %>`
+Default value:<%= code_maybe_block(param[:default]) %>
 
 <% end -%>
 <% if param[:required_features] -%>