(PDOC-184) generate markdown

lib/puppet-strings/json.rb

@@ -34,6 +34,13 @@ def self.tags_to_hashes(tags)
       next t.to_hash if t.respond_to?(:to_hash)
 
       tag = { tag_name: t.tag_name }
+      # grab nested information for @option tags
+      if tag[:tag_name] == 'option'
+        tag[:opt_name] = t.pair.name
+        tag[:opt_text] = t.pair.text
+        tag[:opt_types] = t.pair.types
+        tag[:parent] = t.name
+      end
       tag[:text] = t.text if t.text
       tag[:types] = t.types if t.types
       tag[:name] = t.name if t.name

lib/puppet-strings/markdown/base.rb

@@ -58,8 +58,6 @@ def initialize(registry, component_type)
     { :return_val => 'return',
       :since => 'since',
       :summary => 'summary',
-      :author => 'author',
-      :raise => 'raise',
       :option => 'option' }.each do |method_name, tag_name|
       define_method method_name do
         @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0][:text] unless @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0].nil?
@@ -101,6 +99,20 @@ def examples
       @tags.select { |tag| tag[:tag_name] == 'example' } unless @tags.select { |tag| tag[:tag_name] == 'example' }[0].nil?
     end
 
+    # @return [Array] example tag hashes
+    def raises
+      @tags.select { |tag| tag[:tag_name] == 'raise' } unless @tags.select { |tag| tag[:tag_name] == 'raise' }[0].nil?
+    end
+
+    def options
+      @tags.select { |tag| tag[:tag_name] == 'option' } unless @tags.select { |tag| tag[:tag_name] == 'option' }[0].nil?
+    end
+
+    def options_for_param(parameter_name)
+      opts_for_p = options.select { |o| o[:parent] == parameter_name } unless options.nil?
+      opts_for_p unless opts_for_p.nil? || opts_for_p.length == 0
+    end
+
     # @return [Array] any defaults found for the component
     def defaults
       @registry[:defaults] unless @registry[:defaults].nil?

lib/puppet-strings/markdown/puppet_function.rb

@@ -16,6 +16,27 @@ def initialize(registry)
     def render
       super(@template)
     end
+
+    def type
+      t = @registry[:type]
+      if t =~ /ruby4x/
+        "Ruby 4.x API"
+      elsif t =~ /ruby3/
+        "Ruby 3.x API"
+      elsif t =~ /ruby/
+        "Ruby"
+      else
+        "Puppet Language"
+      end
+    end
+
+    def error_type(r)
+      "`#{r.split(' ')[0]}`"
+    end
+
+    def error_text(r)
+      "#{r.split(' ').drop(1).join(' ')}"
+    end
   end
 
   class PuppetFunction::Signature < Base

lib/puppet-strings/markdown/puppet_resource_type.rb

@@ -20,7 +20,8 @@ def parameters
     end
 
     def regex_in_data_type?(data_type)
-      data_type.match(/\w+\[\/.*\/\]/).length > 0
+      m = data_type.match(/\w+\[\/.*\/\]/)
+      m unless m.nil? || m.length.zero?
     end
   end
 end

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

@@ -1,4 +1,5 @@
 ### <%= name %>
+Type: <%= type %>
 
 <% signatures.each do |sig| -%>
 #### `<%= sig.signature %>`
@@ -10,6 +11,13 @@
 <% if sig.return_val -%>
 Returns: `<%= sig.return_type %>` <%= sig.return_val %>
 
+<% end -%>
+<% if raises -%>
+Raises:
+<% raises.each do |r| -%>
+* <%= error_type(r[:text]) %> <%= error_text(r[:text]) %>
+<% end -%>
+
 <% end -%>
 <% if sig.params -%>
 <% sig.params.each do |param| -%>
@@ -19,6 +27,14 @@ Data type: `<%= param[:types][0] %>`
 
 <%= param[:text] %>
 
+<% if sig.options_for_param(param[:name]) -%>
+Options:
+
+<% sig.options_for_param(param[:name]).each do |o| -%>
+* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+<% end -%>
+
+<% end -%>
 <% end -%>
 <% end -%>
 <% end -%>

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

@@ -9,10 +9,6 @@
 <% see.each do |sa| -%>
 <%= sa[:name] %>
 <%= sa[:text] %>
-<% end -%>
-<% if author -%>
-* **Author** <%= author %>
-
 <% end -%>
 
 <% end -%>
@@ -40,6 +36,14 @@ Data type: `<%= param[:types].join(', ') -%>`
 <% end -%>
 <%= param[:text] %>
 
+<% if options_for_param(param[:name]) -%>
+Options:
+
+<% options_for_param(param[:name]).each do |o| -%>
+* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+<% end -%>
+
+<% end -%>
 <% if defaults && defaults[param[:name]] -%>
 Default value: <%= value_string(defaults[param[:name]]) %>
 

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

@@ -8,17 +8,13 @@
 * **See also**
 <% see.each do |sa| -%>
 <%= sa[:name] %>
-    <%= sa[:text] %>
+<%= sa[:text] %>
 <% end -%>
 
 <% end -%>
 <% if text -%>
 <%= text %>
 <% end %>
-<% if author -%>
-* **Author** <%= author %>
-
-<% end -%>
 <% if examples -%>
 #### Examples
 <% examples.each do |eg| -%>
@@ -39,17 +35,29 @@ The following properties are available in the `<%= name %>` <%= @type %>.
 <% if prop[:values] -%>
 Valid values: <%= prop[:values].map { |value| value_string(value) }.join(', ') %>
 
+<% end -%>
+<% if prop[:isnamevar] -%>
+namevar
+
 <% end -%>
 <% if prop[:aliases] -%>
 Aliases: <%= prop[:aliases].to_s.delete('{').delete('}') %>
 
 <% end -%>
 <% if prop[:data_type] -%>
-Data type: `<%= 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]) %>
 
 <% end -%>
 <%= prop[:description] %>
 
+<% if options_for_param(prop[:name]) -%>
+Options:
+
+<% options_for_param(prop[:name]).each do |o| -%>
+* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+<% end -%>
+
+<% end -%>
 <% if prop[:default] -%>
 Default value: <%= prop[:default] %>
 
@@ -71,13 +79,25 @@ Valid values: <%= param[:values].map { |value| value_string(value) }.join(', ')
 <% if param[:isnamevar] -%>
 namevar
 
+<% end -%>
+<% if param[:aliases] -%>
+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]) %>
 
 <% end -%>
 <%= param[:description] %>
 
+<% if options_for_param(param[:name]) -%>
+Options:
+
+<% options_for_param(param[:name]).each do |o| -%>
+* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+<% end -%>
+
+<% end -%>
 <% if param[:default] -%>
 Default value: <%= value_string(param[:default]) %>
 

lib/puppet-strings/yard/code_objects/function.rb

@@ -84,14 +84,14 @@ def to_hash
     hash[:line] = line
     hash[:type] = @function_type.to_s
     hash[:signatures] = []
-    
+
     if self.has_tag? :overload
       # loop over overloads and append onto the signatures array
       self.tags(:overload).each do |o|
-        hash[:signatures] << { :signature => o.signature, :docstring => PuppetStrings::Json.docstring_to_hash(o.docstring, [:param, :return]) }
+        hash[:signatures] << { :signature => o.signature, :docstring => PuppetStrings::Json.docstring_to_hash(o.docstring, [:param, :option, :return]) }
       end
     else
-      hash[:signatures] << { :signature => self.signature, :docstring =>  PuppetStrings::Json.docstring_to_hash(docstring, [:param, :return]) }
+      hash[:signatures] << { :signature => self.signature, :docstring =>  PuppetStrings::Json.docstring_to_hash(docstring, [:param, :option, :return]) }
     end
 
     hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring)

spec/fixtures/unit/markdown/output.md

@@ -20,8 +20,6 @@
 * **See also**
 www.puppet.com
 
-* **Author** eputnam
-
 
 #### Examples
 ##### This is an example
@@ -32,6 +30,14 @@ class { 'klass':
 }
 ```
 
+##### This is another example
+```puppet
+class { 'klass':
+  param1 => 1,
+  param3 => 'foo',
+}
+```
+
 
 #### Parameters
 
@@ -51,6 +57,11 @@ Data type: `Any`
 
 Second param.
 
+Options:
+
+* **:opt1** `String`: something about opt1
+* **:opt2** `Hash`: a hash of stuff
+
 Default value: `undef`
 
 ##### `param3`
@@ -71,8 +82,6 @@ Default value: 'hi'
 * **See also**
 www.puppet.com
 
-* **Author** eputnam
-
 
 #### Examples
 ##### Here's an example of this type:
@@ -102,6 +111,11 @@ Data type: `Any`
 
 Second param.
 
+Options:
+
+* **:opt1** `String`: something about opt1
+* **:opt2** `Hash`: a hash of stuff
+
 ##### `param3`
 
 Data type: `String`
@@ -130,8 +144,6 @@ be manipulated through the `apt-key` command.
 If Puppet is given the location of a key file which looks like an absolute
 path this type will autorequire that file.
 
-* **Author** eputnam
-
 #### Examples
 ##### here's an example
 ```puppet
@@ -174,8 +186,6 @@ The ID of the key you want to manage.
 
 An example database server resource type.
 
-* **Author** eputnam
-
 #### Examples
 ##### here's an example
 ```puppet
@@ -236,13 +246,17 @@ Default value: `false`
 ## Functions
 
 ### func
+Type: Puppet Language
 
 #### `func(Integer $param1, Any $param2, String $param3 = hi)`
 
 A simple Puppet function.
 
 Returns: `Undef` Returns nothing.
 
+Raises:
+* `SomeError` this is some error
+
 ##### `param1`
 
 Data type: `Integer`
@@ -261,7 +275,12 @@ Data type: `String`
 
 Third param.
 
+Options:
+
+* **:param3opt** `Array`: Something about this option
+
 ### func4x
+Type: Ruby 4.x API
 
 #### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)`
 
@@ -281,6 +300,11 @@ Data type: `Any`
 
 The second parameter.
 
+Options:
+
+* **:option** `String`: an option
+* **:option2** `String`: another option
+
 ##### `param3`
 
 Data type: `Optional[Array[String]]`
@@ -306,6 +330,7 @@ Data type: `Callable`
 The block parameter.
 
 ### func4x_1
+Type: Ruby 4.x API
 
 #### `func4x_1(Integer $param1)`