From d3284114a3f65af4553a31eb122af370f2b7570f Mon Sep 17 00:00:00 2001 From: Daniel Parks Date: Mon, 26 Sep 2022 16:54:31 -0700 Subject: [PATCH] (#223) Use code blocks as appropriate in Markdown MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sometimes data types, default values, and other code outputted in Markdown documentation is multiline. When that’s the case, it’s cleaner to use a code block (below) rather and inline code (`code`). ``` example code block with two lines ``` This updates the Markdown template code to use code blocks in many places if the code in question contains a newline. Thanks to @crazymind1337 for the example of a multiline type alias! --- lib/puppet-strings/markdown/base.rb | 4 + lib/puppet-strings/markdown/helpers.rb | 21 +++++ .../templates/classes_and_defines.erb | 4 +- .../markdown/templates/data_type.erb | 10 +-- .../markdown/templates/data_type_function.erb | 2 +- .../markdown/templates/function.erb | 2 +- .../markdown/templates/puppet_task.erb | 2 +- .../markdown/templates/resource_type.erb | 2 +- spec/unit/puppet-strings/markdown_spec.rb | 82 +++++++++++++++++++ 9 files changed, 116 insertions(+), 13 deletions(-) create mode 100644 lib/puppet-strings/markdown/helpers.rb diff --git a/lib/puppet-strings/markdown/base.rb b/lib/puppet-strings/markdown/base.rb index 54110d3ad..22435a112 100644 --- a/lib/puppet-strings/markdown/base.rb +++ b/lib/puppet-strings/markdown/base.rb @@ -3,6 +3,7 @@ require 'puppet-strings' require 'puppet-strings/json' require 'puppet-strings/yard' +require 'puppet-strings/markdown/helpers' # Implements classes that make elements in a YARD::Registry hash easily accessible for template. module PuppetStrings::Markdown @@ -50,6 +51,9 @@ module PuppetStrings::Markdown # ") inherits foo::bar {\n" + # "}"} class Base + # Helpers for ERB templates + include PuppetStrings::Markdown::Helpers + # Set or return the name of the group # # @param [Optional[String]] Name of the group to set diff --git a/lib/puppet-strings/markdown/helpers.rb b/lib/puppet-strings/markdown/helpers.rb new file mode 100644 index 000000000..90a29b322 --- /dev/null +++ b/lib/puppet-strings/markdown/helpers.rb @@ -0,0 +1,21 @@ +# frozen_string_literal: true + +# Helpers for rendering Markdown +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 ```. + # + # @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. + # @returns [String] Markdown + def code_maybe_block(code, type: :puppet, block_prefix: "\n\n", inline_prefix: ' ') + if code.include?("\n") + "#{block_prefix}```#{type}\n#{code}\n```" + else + "#{inline_prefix}`#{code}`" + end + end +end diff --git a/lib/puppet-strings/markdown/templates/classes_and_defines.erb b/lib/puppet-strings/markdown/templates/classes_and_defines.erb index 83c64ec2f..e52791573 100644 --- a/lib/puppet-strings/markdown/templates/classes_and_defines.erb +++ b/lib/puppet-strings/markdown/templates/classes_and_defines.erb @@ -57,7 +57,7 @@ The following parameters are available in the `<%= name %>` <%= @type %>: ##### `<%= param[:name] %>` <% if param[:types] -%> -Data type: `<%= param[:types].join(', ') -%>` +Data type:<%= code_maybe_block(param[:types].join(', ')) %> <% end -%> <%= param[:text] %> @@ -79,7 +79,7 @@ Options: <% end -%> <% if defaults && defaults[param[:name]] -%> -Default value: `<%= defaults[param[:name]] %>` +Default value:<%= code_maybe_block(defaults[param[:name]]) %> <% end -%> <% end -%> diff --git a/lib/puppet-strings/markdown/templates/data_type.erb b/lib/puppet-strings/markdown/templates/data_type.erb index e55dda20d..718de0e92 100644 --- a/lib/puppet-strings/markdown/templates/data_type.erb +++ b/lib/puppet-strings/markdown/templates/data_type.erb @@ -45,11 +45,7 @@ <% end -%> <% end -%> <% if alias_of -%> -Alias of - -```puppet -<%= alias_of %> -``` +Alias of<%= code_maybe_block(alias_of) %> <% end -%> <% if params -%> @@ -65,7 +61,7 @@ The following parameters are available in the `<%= name %>` <%= @type %>: ##### `<%= param[:name] %>` <% if param[:types] -%> -Data type: `<%= param[:types].join(', ') -%>` +Data type:<%= code_maybe_block(param[:types].join(', ')) %> <% end -%> <%= param[:text] %> @@ -87,7 +83,7 @@ Options: <% end -%> <% if defaults && defaults[param[:name]] -%> -Default value: `<%= defaults[param[:name]] %>` +Default value:<%= code_maybe_block(defaults[param[:name]]) %> <% end -%> <% end -%> diff --git a/lib/puppet-strings/markdown/templates/data_type_function.erb b/lib/puppet-strings/markdown/templates/data_type_function.erb index 13d7bf953..afb8cbd04 100644 --- a/lib/puppet-strings/markdown/templates/data_type_function.erb +++ b/lib/puppet-strings/markdown/templates/data_type_function.erb @@ -43,7 +43,7 @@ Raises: <% params.each do |param| -%> ##### `<%= param[:name] %>` -Data type: `<%= param[:types][0] %>` +Data type:<%= code_maybe_block(param[:types][0]) %> <%= param[:text] %> diff --git a/lib/puppet-strings/markdown/templates/function.erb b/lib/puppet-strings/markdown/templates/function.erb index 6466521b3..9f096363f 100644 --- a/lib/puppet-strings/markdown/templates/function.erb +++ b/lib/puppet-strings/markdown/templates/function.erb @@ -77,7 +77,7 @@ Raises: <% sig.params.each do |param| -%> ##### `<%= param[:name] %>` -Data type: `<%= param[:types][0] %>` +Data type:<%= code_maybe_block(param[:types][0]) %> <%= param[:text] %> diff --git a/lib/puppet-strings/markdown/templates/puppet_task.erb b/lib/puppet-strings/markdown/templates/puppet_task.erb index d12872d67..1f9e2c5ac 100644 --- a/lib/puppet-strings/markdown/templates/puppet_task.erb +++ b/lib/puppet-strings/markdown/templates/puppet_task.erb @@ -19,7 +19,7 @@ ##### `<%= param[:name] %>` <% if param[:types] -%> -Data type: `<%= param[:types].join(', ') -%>` +Data type:<%= code_maybe_block(param[:types].join(', ')) %> <% end -%> <%= param[:text] %> diff --git a/lib/puppet-strings/markdown/templates/resource_type.erb b/lib/puppet-strings/markdown/templates/resource_type.erb index 6b407f6fe..0081e843d 100644 --- a/lib/puppet-strings/markdown/templates/resource_type.erb +++ b/lib/puppet-strings/markdown/templates/resource_type.erb @@ -87,7 +87,7 @@ Options: <% end -%> <% if prop[:default] -%> -Default value: `<%= prop[:default] %>` +Default value:<%= code_maybe_block(prop[:default], type: :ruby) %> <% end -%> <% end -%> diff --git a/spec/unit/puppet-strings/markdown_spec.rb b/spec/unit/puppet-strings/markdown_spec.rb index 0682875ae..8cbc3abee 100644 --- a/spec/unit/puppet-strings/markdown_spec.rb +++ b/spec/unit/puppet-strings/markdown_spec.rb @@ -258,4 +258,86 @@ def parse_data_type_content MARKDOWN end + + it 'renders single-line data types with inline code' do + expect(YARD::Parser::SourceParser.parse_string(<<~'PUPPET', :puppet).enumerator.length).to eq(1) + # @summary it’s for testing + type MyEnum = Enum[a, b] + PUPPET + + expect(described_class.generate).to match(%r{^Alias of `Enum\[a, b\]`$}) + end + + it 'renders multi-line data types with inline code' do + expect(YARD::Parser::SourceParser.parse_string(<<~'PUPPET', :puppet).enumerator.length).to eq(1) + # summary Test Type + # + type Test_module::Test_type = Hash[ + Pattern[/^[a-z][a-z0-9_-]*$/], + Struct[ + { + param1 => String[1], + param2 => Stdlib::Absolutepath, + paramX => Boolean, + } + ] + ] + PUPPET + + expect(described_class.generate).to include(<<~'MARKDOWN') + Alias of + + ```puppet + Hash[Pattern[/^[a-z][a-z0-9_-]*$/], Struct[ + { + param1 => String[1], + param2 => Stdlib::Absolutepath, + paramX => Boolean, + } + ]] + ``` + MARKDOWN + end + + it 'renders single-line default values with inline code' do + expect(YARD::Parser::SourceParser.parse_string(<<~'PUPPET', :puppet).enumerator.length).to eq(1) + # @summary Test + class myclass ( + String $os = 'linux', + ) { + } + PUPPET + + expect(described_class.generate).to include(<<~'MARKDOWN') + Default value: `'linux'` + MARKDOWN + end + + it 'renders multi-line default values with a code block' do + skip('Broken by https://tickets.puppetlabs.com/browse/PUP-11632') + + expect(YARD::Parser::SourceParser.parse_string(<<~'PUPPET', :puppet).enumerator.length).to eq(1) + # @summary Test + class myclass ( + String $os = $facts['kernel'] ? { + 'Linux' => 'linux', + 'Darwin' => 'darwin', + default => $facts['kernel'], + }, + ) { + } + PUPPET + + expect(described_class.generate).to include(<<~'MARKDOWN') + Default value: + + ```puppet + $facts['kernel'] ? { + 'Linux' => 'linux', + 'Darwin' => 'darwin', + default => $facts['kernel'] + } + ``` + MARKDOWN + end end