diff --git a/lib/puppet-strings/markdown/templates/classes_and_defines.erb b/lib/puppet-strings/markdown/templates/classes_and_defines.erb index afacde4..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 %> @@ -17,22 +15,28 @@ <% if see -%> * **See also** <% see.each do |sa| -%> +<% if sa[:name] -%> <%= sa[:name] %> +<% end -%> +<% if sa[:text] -%> <%= sa[:text] %> <% end -%> +<% end -%> <% end -%> <% if examples -%> #### Examples + <% examples.each do |eg| -%> ##### <%= eg[:name] %> + ```puppet <%= eg[:text] %> ``` <% end -%> <% end -%> -<% if params %> +<% if params -%> #### Parameters The following parameters are available in the `<%= name %>` <%= @type %>. @@ -60,4 +64,3 @@ Default value: <%= value_string(defaults[param[:name]]) %> <% end -%> <% end -%> <% end -%> - 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..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 %> @@ -17,21 +15,28 @@ <% if see -%> * **See also** <% see.each do |sa| -%> +<% if sa[:name] -%> <%= sa[:name] %> +<% end -%> +<% if sa[:text] -%> <%= sa[:text] %> <% end -%> +<% end -%> <% 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 %>. @@ -111,4 +116,3 @@ Default value: <%= value_string(param[:default]) %> <% end -%> <% end -%> <% end -%> - 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..307c620 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 @@ -28,9 +41,10 @@ An overview for a simple class. * **See also** www.puppet.com - #### Examples + ##### This is an example + ```puppet class { 'klass': param1 => 1, @@ -39,6 +53,7 @@ class { 'klass': ``` ##### This is another example + ```puppet class { 'klass': param1 => 1, @@ -46,7 +61,6 @@ class { 'klass': } ``` - #### Parameters The following parameters are available in the `klass` class. @@ -80,7 +94,6 @@ Third param. Default value: 'hi' - ## Defined types ### klass::dt @@ -92,9 +105,10 @@ An overview for a simple defined type. * **See also** www.puppet.com - #### Examples + ##### Here's an example of this type: + ```puppet klass::dt { 'foo': param1 => 33, @@ -102,7 +116,6 @@ klass::dt { 'foo': } ``` - #### Parameters The following parameters are available in the `klass::dt` defined type. @@ -142,7 +155,6 @@ Fourth param. Default value: `true` - ## Resource types ### apt_key @@ -155,7 +167,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' @@ -191,13 +205,14 @@ _*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. #### Examples + ##### here's an example + ```puppet database { 'foo': address => 'qux.baz.bar', @@ -252,10 +267,10 @@ Whether or not to encrypt the database. Default value: `false` - ## Functions ### func + Type: Puppet Language A simple Puppet function. @@ -292,6 +307,7 @@ Options: * **:param3opt** `Array`: Something about this option ### func3x + Type: Ruby 3.x API Documentation for an example 3.x function. @@ -315,6 +331,7 @@ Data type: `Integer` The second parameter. ### func4x + Type: Ruby 4.x API An example 4.x function. @@ -367,6 +384,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..710cef9 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 @@ -28,9 +41,10 @@ An overview for a simple class. * **See also** www.puppet.com - #### Examples + ##### This is an example + ```puppet class { 'klass': param1 => 1, @@ -39,6 +53,7 @@ class { 'klass': ``` ##### This is another example + ```puppet class { 'klass': param1 => 1, @@ -46,7 +61,6 @@ class { 'klass': } ``` - #### Parameters The following parameters are available in the `klass` class. @@ -80,7 +94,6 @@ Third param. Default value: 'hi' - ## Defined types ### klass::dt @@ -92,9 +105,10 @@ An overview for a simple defined type. * **See also** www.puppet.com - #### Examples + ##### Here's an example of this type: + ```puppet klass::dt { 'foo': param1 => 33, @@ -102,7 +116,6 @@ klass::dt { 'foo': } ``` - #### Parameters The following parameters are available in the `klass::dt` defined type. @@ -142,7 +155,6 @@ Fourth param. Default value: `true` - ## Resource types ### apt_key @@ -155,7 +167,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' @@ -191,13 +205,14 @@ _*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. #### Examples + ##### here's an example + ```puppet database { 'foo': address => 'qux.baz.bar', @@ -252,10 +267,10 @@ Whether or not to encrypt the database. Default value: `false` - ## Functions ### func + Type: Puppet Language A simple Puppet function. @@ -292,6 +307,7 @@ Options: * **:param3opt** `Array`: Something about this option ### func3x + Type: Ruby 3.x API Documentation for an example 3.x function. @@ -315,6 +331,7 @@ Data type: `Integer` The second parameter. ### func4x + Type: Ruby 4.x API An example 4.x function. @@ -367,6 +384,7 @@ Data type: `Callable` The block parameter. ### func4x_1 + Type: Ruby 4.x API An example 4.x function with only one signature. @@ -423,7 +441,6 @@ Path to file you want backup to A simple plan. - #### Parameters The following parameters are available in the `plann` plan. @@ -448,4 +465,3 @@ Third param. Default value: 1 -