From d9065e6f2e81700a1ddb47a7e740d7b3b21ba5d6 Mon Sep 17 00:00:00 2001 From: John Lyman Date: Fri, 16 Mar 2018 13:18:08 +0000 Subject: [PATCH 1/3] (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. From ca26677cad418bb66944d06b1d1d86779fb58213 Mon Sep 17 00:00:00 2001 From: John Lyman Date: Fri, 16 Mar 2018 13:21:59 +0000 Subject: [PATCH 2/3] (PDOC-233) Make markdown white space formatting consistent Replace arbitrary double blank lines with a single blank lines. --- .../markdown/templates/classes_and_defines.erb | 7 +++++-- .../markdown/templates/resource_type.erb | 5 ++++- spec/fixtures/unit/markdown/output.md | 8 -------- spec/fixtures/unit/markdown/output_with_plan.md | 10 ---------- 4 files changed, 9 insertions(+), 21 deletions(-) diff --git a/lib/puppet-strings/markdown/templates/classes_and_defines.erb b/lib/puppet-strings/markdown/templates/classes_and_defines.erb index 57c58dd..aa89832 100644 --- a/lib/puppet-strings/markdown/templates/classes_and_defines.erb +++ b/lib/puppet-strings/markdown/templates/classes_and_defines.erb @@ -17,9 +17,13 @@ <% if see -%> * **See also** <% see.each do |sa| -%> +<% if sa[:name] -%> <%= sa[:name] %> +<% end -%> +<% if sa[:text] -%> <%= sa[:text] %> <% end -%> +<% end -%> <% end -%> <% if examples -%> @@ -34,7 +38,7 @@ <% end -%> <% end -%> -<% if params %> +<% if params -%> #### Parameters The following parameters are available in the `<%= name %>` <%= @type %>. @@ -62,4 +66,3 @@ Default value: <%= value_string(defaults[param[:name]]) %> <% end -%> <% end -%> <% end -%> - diff --git a/lib/puppet-strings/markdown/templates/resource_type.erb b/lib/puppet-strings/markdown/templates/resource_type.erb index 064502b..1feb202 100644 --- a/lib/puppet-strings/markdown/templates/resource_type.erb +++ b/lib/puppet-strings/markdown/templates/resource_type.erb @@ -17,9 +17,13 @@ <% if see -%> * **See also** <% see.each do |sa| -%> +<% if sa[:name] -%> <%= sa[:name] %> +<% end -%> +<% if sa[:text] -%> <%= sa[:text] %> <% end -%> +<% end -%> <% end -%> <% if examples -%> @@ -114,4 +118,3 @@ Default value: <%= value_string(param[:default]) %> <% end -%> <% end -%> <% end -%> - diff --git a/spec/fixtures/unit/markdown/output.md b/spec/fixtures/unit/markdown/output.md index ee09ed4..307c620 100644 --- a/spec/fixtures/unit/markdown/output.md +++ b/spec/fixtures/unit/markdown/output.md @@ -41,7 +41,6 @@ An overview for a simple class. * **See also** www.puppet.com - #### Examples ##### This is an example @@ -62,7 +61,6 @@ class { 'klass': } ``` - #### Parameters The following parameters are available in the `klass` class. @@ -96,7 +94,6 @@ Third param. Default value: 'hi' - ## Defined types ### klass::dt @@ -108,7 +105,6 @@ An overview for a simple defined type. * **See also** www.puppet.com - #### Examples ##### Here's an example of this type: @@ -120,7 +116,6 @@ klass::dt { 'foo': } ``` - #### Parameters The following parameters are available in the `klass::dt` defined type. @@ -160,7 +155,6 @@ Fourth param. Default value: `true` - ## Resource types ### apt_key @@ -211,7 +205,6 @@ _*this data type contains a regex that may not be accurately reflected in genera The ID of the key you want to manage. - ### database An example database server type. @@ -274,7 +267,6 @@ Whether or not to encrypt the database. Default value: `false` - ## Functions ### func diff --git a/spec/fixtures/unit/markdown/output_with_plan.md b/spec/fixtures/unit/markdown/output_with_plan.md index fbd6e07..710cef9 100644 --- a/spec/fixtures/unit/markdown/output_with_plan.md +++ b/spec/fixtures/unit/markdown/output_with_plan.md @@ -41,7 +41,6 @@ An overview for a simple class. * **See also** www.puppet.com - #### Examples ##### This is an example @@ -62,7 +61,6 @@ class { 'klass': } ``` - #### Parameters The following parameters are available in the `klass` class. @@ -96,7 +94,6 @@ Third param. Default value: 'hi' - ## Defined types ### klass::dt @@ -108,7 +105,6 @@ An overview for a simple defined type. * **See also** www.puppet.com - #### Examples ##### Here's an example of this type: @@ -120,7 +116,6 @@ klass::dt { 'foo': } ``` - #### Parameters The following parameters are available in the `klass::dt` defined type. @@ -160,7 +155,6 @@ Fourth param. Default value: `true` - ## Resource types ### apt_key @@ -211,7 +205,6 @@ _*this data type contains a regex that may not be accurately reflected in genera The ID of the key you want to manage. - ### database An example database server type. @@ -274,7 +267,6 @@ Whether or not to encrypt the database. Default value: `false` - ## Functions ### func @@ -449,7 +441,6 @@ Path to file you want backup to A simple plan. - #### Parameters The following parameters are available in the `plann` plan. @@ -474,4 +465,3 @@ Third param. Default value: 1 - From 6ba035092829ec42d94dcdee0684aa47711998e3 Mon Sep 17 00:00:00 2001 From: John Lyman Date: Fri, 16 Mar 2018 13:42:21 +0000 Subject: [PATCH 3/3] (PDOC-233) Simplify logic for white space formatting of summary Instead of specifying white space after each conditional, just add a blank line at the end of the conditional similar to the `function.erb` template. --- lib/puppet-strings/markdown/templates/classes_and_defines.erb | 4 +--- lib/puppet-strings/markdown/templates/resource_type.erb | 4 +--- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/lib/puppet-strings/markdown/templates/classes_and_defines.erb b/lib/puppet-strings/markdown/templates/classes_and_defines.erb index aa89832..cc8c76e 100644 --- a/lib/puppet-strings/markdown/templates/classes_and_defines.erb +++ b/lib/puppet-strings/markdown/templates/classes_and_defines.erb @@ -2,14 +2,12 @@ <% if text -%> <%= text %> - <% elsif summary -%> <%= summary %> - <% else -%> <%= "The #{name} class." %> - <% end -%> + <% if since -%> * **Since** <%= since %> diff --git a/lib/puppet-strings/markdown/templates/resource_type.erb b/lib/puppet-strings/markdown/templates/resource_type.erb index 1feb202..9c9a045 100644 --- a/lib/puppet-strings/markdown/templates/resource_type.erb +++ b/lib/puppet-strings/markdown/templates/resource_type.erb @@ -2,14 +2,12 @@ <% if text -%> <%= text %> - <% elsif summary -%> <%= summary %> - <% else -%> <%= "The #{name} type." %> - <% end -%> + <% if since -%> * **Since** <%= since %>