From d9065e6f2e81700a1ddb47a7e740d7b3b21ba5d6 Mon Sep 17 00:00:00 2001 From: John Lyman Date: Fri, 16 Mar 2018 13:18:08 +0000 Subject: [PATCH] (PDOC-233) Increase chances of markdown rendering correctly Some variants of markdown do not convert atx-style headers correctly unless they are surrounded by blank lines. This commit adds blank lines to increase chances of rendering when using those variants while still maintaining compatibly with variants that do not require the surrounding blank lines. Also increases readability when viewing the raw markdown file. --- .../templates/classes_and_defines.erb | 2 ++ .../markdown/templates/function.erb | 5 ++-- .../markdown/templates/resource_type.erb | 5 +++- .../markdown/templates/table_of_contents.erb | 5 ++++ spec/fixtures/unit/markdown/output.md | 26 +++++++++++++++++++ .../unit/markdown/output_with_plan.md | 26 +++++++++++++++++++ 6 files changed, 65 insertions(+), 4 deletions(-) diff --git a/lib/puppet-strings/markdown/templates/classes_and_defines.erb b/lib/puppet-strings/markdown/templates/classes_and_defines.erb index afacde4..57c58dd 100644 --- a/lib/puppet-strings/markdown/templates/classes_and_defines.erb +++ b/lib/puppet-strings/markdown/templates/classes_and_defines.erb @@ -24,8 +24,10 @@ <% end -%> <% if examples -%> #### Examples + <% examples.each do |eg| -%> ##### <%= eg[:name] %> + ```puppet <%= eg[:text] %> ``` diff --git a/lib/puppet-strings/markdown/templates/function.erb b/lib/puppet-strings/markdown/templates/function.erb index 6f6a15b..2d96066 100644 --- a/lib/puppet-strings/markdown/templates/function.erb +++ b/lib/puppet-strings/markdown/templates/function.erb @@ -1,16 +1,15 @@ ### <%= name %> + Type: <%= type %> <% if text -%> <%= text %> - <% elsif summary -%> <%= summary %> - <% else -%> <%= "The #{name} class." %> - <% end -%> + <% signatures.each do |sig| -%> #### `<%= sig.signature %>` diff --git a/lib/puppet-strings/markdown/templates/resource_type.erb b/lib/puppet-strings/markdown/templates/resource_type.erb index f517f40..064502b 100644 --- a/lib/puppet-strings/markdown/templates/resource_type.erb +++ b/lib/puppet-strings/markdown/templates/resource_type.erb @@ -24,14 +24,17 @@ <% end -%> <% if examples -%> #### Examples + <% examples.each do |eg| -%> ##### <%= eg[:name] %> + ```puppet <%= eg[:text] %> ``` + <% end -%> <% end -%> -<% if properties %> +<% if properties -%> #### Properties The following properties are available in the `<%= name %>` <%= @type %>. diff --git a/lib/puppet-strings/markdown/templates/table_of_contents.erb b/lib/puppet-strings/markdown/templates/table_of_contents.erb index c2b4e18..d275512 100644 --- a/lib/puppet-strings/markdown/templates/table_of_contents.erb +++ b/lib/puppet-strings/markdown/templates/table_of_contents.erb @@ -1,13 +1,17 @@ <% if group.length > 0 -%> ## <%= group_name %> + <% if priv -%> ### Public <%= group_name %> + <% group.each do |item| -%> <% unless item[:private] -%> * [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %> <% end -%> <% end -%> + ### Private <%= group_name %> + <% group.each do |item| -%> <% if item[:private] -%> * `<%= item[:name] %>`: <%= item[:desc] %> @@ -18,4 +22,5 @@ * [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %> <% end -%> <% end -%> + <% end -%> diff --git a/spec/fixtures/unit/markdown/output.md b/spec/fixtures/unit/markdown/output.md index 51a160d..ee09ed4 100644 --- a/spec/fixtures/unit/markdown/output.md +++ b/spec/fixtures/unit/markdown/output.md @@ -1,22 +1,35 @@ # Reference ## Classes + ### Public Classes + * [`klass`](#klass): A simple class. + ### Private Classes + * `noparams`: Overview for class noparams + ## Defined types + * [`klass::dt`](#klassdt): A simple defined type. + ## Resource types + * [`apt_key`](#apt_key): Example resource type using the new API. * [`database`](#database): An example database server type. + ## Functions + * [`func`](#func): A simple Puppet function. * [`func3x`](#func3x): Documentation for an example 3.x function. * [`func4x`](#func4x): An example 4.x function. * [`func4x_1`](#func4x_1): An example 4.x function with only one signature. + ## Tasks + * [`(stdin)`](#(stdin)): Allows you to backup your database to local file. + ## Classes ### klass @@ -30,7 +43,9 @@ www.puppet.com #### Examples + ##### This is an example + ```puppet class { 'klass': param1 => 1, @@ -39,6 +54,7 @@ class { 'klass': ``` ##### This is another example + ```puppet class { 'klass': param1 => 1, @@ -94,7 +110,9 @@ www.puppet.com #### Examples + ##### Here's an example of this type: + ```puppet klass::dt { 'foo': param1 => 33, @@ -155,7 +173,9 @@ If Puppet is given the location of a key file which looks like an absolute path this type will autorequire that file. #### Examples + ##### here's an example + ```puppet apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F': source => 'http://apt.puppetlabs.com/pubkey.gpg' @@ -197,7 +217,9 @@ The ID of the key you want to manage. An example database server type. #### Examples + ##### here's an example + ```puppet database { 'foo': address => 'qux.baz.bar', @@ -256,6 +278,7 @@ Default value: `false` ## Functions ### func + Type: Puppet Language A simple Puppet function. @@ -292,6 +315,7 @@ Options: * **:param3opt** `Array`: Something about this option ### func3x + Type: Ruby 3.x API Documentation for an example 3.x function. @@ -315,6 +339,7 @@ Data type: `Integer` The second parameter. ### func4x + Type: Ruby 4.x API An example 4.x function. @@ -367,6 +392,7 @@ Data type: `Callable` The block parameter. ### func4x_1 + Type: Ruby 4.x API An example 4.x function with only one signature. diff --git a/spec/fixtures/unit/markdown/output_with_plan.md b/spec/fixtures/unit/markdown/output_with_plan.md index 4b08b94..fbd6e07 100644 --- a/spec/fixtures/unit/markdown/output_with_plan.md +++ b/spec/fixtures/unit/markdown/output_with_plan.md @@ -1,22 +1,35 @@ # Reference ## Classes + ### Public Classes + * [`klass`](#klass): A simple class. + ### Private Classes + * `noparams`: Overview for class noparams + ## Defined types + * [`klass::dt`](#klassdt): A simple defined type. + ## Resource types + * [`apt_key`](#apt_key): Example resource type using the new API. * [`database`](#database): An example database server type. + ## Functions + * [`func`](#func): A simple Puppet function. * [`func3x`](#func3x): Documentation for an example 3.x function. * [`func4x`](#func4x): An example 4.x function. * [`func4x_1`](#func4x_1): An example 4.x function with only one signature. + ## Tasks + * [`(stdin)`](#(stdin)): Allows you to backup your database to local file. + ## Classes ### klass @@ -30,7 +43,9 @@ www.puppet.com #### Examples + ##### This is an example + ```puppet class { 'klass': param1 => 1, @@ -39,6 +54,7 @@ class { 'klass': ``` ##### This is another example + ```puppet class { 'klass': param1 => 1, @@ -94,7 +110,9 @@ www.puppet.com #### Examples + ##### Here's an example of this type: + ```puppet klass::dt { 'foo': param1 => 33, @@ -155,7 +173,9 @@ If Puppet is given the location of a key file which looks like an absolute path this type will autorequire that file. #### Examples + ##### here's an example + ```puppet apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F': source => 'http://apt.puppetlabs.com/pubkey.gpg' @@ -197,7 +217,9 @@ The ID of the key you want to manage. An example database server type. #### Examples + ##### here's an example + ```puppet database { 'foo': address => 'qux.baz.bar', @@ -256,6 +278,7 @@ Default value: `false` ## Functions ### func + Type: Puppet Language A simple Puppet function. @@ -292,6 +315,7 @@ Options: * **:param3opt** `Array`: Something about this option ### func3x + Type: Ruby 3.x API Documentation for an example 3.x function. @@ -315,6 +339,7 @@ Data type: `Integer` The second parameter. ### func4x + Type: Ruby 4.x API An example 4.x function. @@ -367,6 +392,7 @@ Data type: `Callable` The block parameter. ### func4x_1 + Type: Ruby 4.x API An example 4.x function with only one signature.