openvox-strings 5.0.0

data/lib/openvox-strings/markdown/resource_type.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/markdown/base'
+
+module OpenvoxStrings::Markdown
+  # Generates Markdown for a Puppet Resource Type.
+  class ResourceType < Base
+    group_name 'Resource types'
+    yard_types [:puppet_type]
+
+    def initialize(registry)
+      @template = 'resource_type.erb'
+      super(registry, 'type')
+    end
+
+    def render
+      super(@template)
+    end
+
+    def properties
+      return nil unless @registry[:properties]
+
+      @registry[:properties].sort_by { |p| p[:name] }
+    end
+
+    def checks
+      return nil unless @registry[:checks]
+
+      @registry[:checks].sort_by { |p| p[:name] }
+    end
+
+    # "checks" (such as "onlyif" or "creates") are another type of property
+    def properties_and_checks
+      return nil if properties.nil? && checks.nil?
+
+      ((properties || []) + (checks || [])).sort_by { |p| p[:name] }.map do |prop|
+        prop[:link] = clean_link("$#{name}::#{prop[:name]}")
+        prop
+      end
+    end
+
+    def parameters
+      return nil unless @registry[:parameters]
+
+      @registry[:parameters].sort_by { |p| p[:name] }.map do |param|
+        param[:link] = clean_link("$#{name}::#{param[:name]}")
+        param
+      end
+    end
+
+    def regex_in_data_type?(data_type)
+      m = data_type.match(%r{\w+\[/.*/\]})
+      m unless m.nil? || m.to_a.empty?
+    end
+  end
+end

data/lib/openvox-strings/markdown/templates/classes_and_defines.erb

@@ -0,0 +1,94 @@
+### <a name="<%= link %>"></a>`<%= name %>`
+
+<% if text -%>
+<%= text %>
+<% elsif summary -%>
+<%= summary %>
+<% else -%>
+<%= "The #{name} class." %>
+<% end -%>
+
+<% if deprecated -%>
+* **DEPRECATED** <%= deprecated %>
+
+<% end -%>
+<% if todo -%>
+* **TODO** <%= todo %>
+
+<% end -%>
+<% if note -%>
+* **Note** <%= note %>
+
+<% end -%>
+<% if since -%>
+* **Since** <%= since %>
+
+<% end -%>
+<% 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 -%>
+#### Parameters
+
+The following parameters are available in the `<%= name %>` <%= @type %>:
+
+<% params.each do |param| -%>
+* [`<%= param[:name] %>`](#<%= param[:link] %>)
+<% end -%>
+
+<% params.each do |param| -%>
+##### <a name="<%= param[:link] %>"></a>`<%= param[:name] %>`
+
+<% if param[:types] -%>
+Data type:<%= code_maybe_block(param[:types].join(', ')) %>
+
+<% end -%>
+<%= param[:text] %>
+
+<% if options_for_param(param[:name]) -%>
+Options:
+
+<% options_for_param(param[:name]).each do |o| -%>
+<% if o[:opt_types] -%>
+* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+<% else -%>
+* **<%= o[:opt_name] %>**: <%= o[:opt_text] %>
+<% end -%>
+<% end -%>
+
+<% end -%>
+<% if enums_for_param(param[:name]) -%>
+Options:
+
+<% enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
+<% end -%>
+<% if defaults && defaults[param[:name]] -%>
+Default value:<%= code_maybe_block(defaults[param[:name]]) %>
+
+<% end -%>
+<% end -%>
+<% end -%>

data/lib/openvox-strings/markdown/templates/data_type.erb

@@ -0,0 +1,101 @@
+### <a name="<%= link %>"></a>`<%= name %>`
+
+<% if text -%>
+<%= text %>
+<% elsif summary -%>
+<%= summary %>
+<% else -%>
+<%= "The #{name} data type." %>
+<% end -%>
+
+<% if deprecated -%>
+* **DEPRECATED** <%= deprecated %>
+
+<% end -%>
+<% if todo -%>
+* **TODO** <%= todo %>
+
+<% end -%>
+<% if note -%>
+* **Note** <%= note %>
+
+<% end -%>
+<% if since -%>
+* **Since** <%= since %>
+
+<% end -%>
+<% 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 alias_of -%>
+Alias of<%= code_maybe_block(alias_of) %>
+
+<% end -%>
+<% if params -%>
+#### Parameters
+
+The following parameters are available in the `<%= name %>` <%= @type %>:
+
+<% params.each do |param| -%>
+* [`<%= param[:name] %>`](#<%= param[:link] %>)
+<% end -%>
+
+<% params.each do |param| -%>
+##### <a name="<%= param[:link] %>"></a>`<%= param[:name] %>`
+
+<% if param[:types] -%>
+Data type:<%= code_maybe_block(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 enums_for_param(param[:name]) -%>
+Options:
+
+<% enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
+<% end -%>
+<% if defaults && defaults[param[:name]] -%>
+Default value:<%= code_maybe_block(defaults[param[:name]]) %>
+
+<% end -%>
+<% end -%>
+<% end -%>
+<% if functions -%>
+#### Functions
+
+The following functions are available in the `<%= name %>` <%= @type %>.
+
+<% functions.each do |func| -%><%= func.render -%><% end -%>
+<% end -%>

data/lib/openvox-strings/markdown/templates/data_type_function.erb

@@ -0,0 +1,67 @@
+### <a name="<%= link %>"></a>`<%= name %>`
+
+#### `<%= signature %>`
+
+<% if text -%>
+<%= text %>
+
+<% elsif summary -%>
+<%= summary %>
+
+<% else -%>
+<%= "The #{name} function." %>
+
+<% end -%>
+<% if note -%>
+* **Note** <%= note %>
+
+<% end -%>
+<% if return_type -%>
+Returns: `<%= return_type %>`<% if return_val %> <%= return_val %><% end %>
+
+<% end -%>
+<% if raises -%>
+Raises:
+<% raises.each do |r| -%>
+* <%= error_type(r[:text]) %> <%= error_text(r[:text]) %>
+<% end -%>
+
+<% end -%>
+<% if examples -%>
+##### Examples
+
+<% examples.each do |eg| -%>
+###### <%= eg[:name] %>
+
+```puppet
+<%= eg[:text] %>
+```
+
+<% end -%>
+<% end -%>
+<% if params -%>
+<% params.each do |param| -%>
+##### `<%= param[:name]  %>`
+
+Data type:<%= code_maybe_block(param[:types][0]) %>
+
+<%= 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 enums_for_param(param[:name]) -%>
+Options:
+
+<% enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
+<% end -%>
+<% end -%>
+<% end -%>

data/lib/openvox-strings/markdown/templates/function.erb

@@ -0,0 +1,106 @@
+### <a name="<%= link %>"></a>`<%= name %>`
+
+Type: <%= type %>
+
+<% if text -%>
+<%= text %>
+
+<% elsif summary -%>
+<%= summary %>
+
+<% else -%>
+<%= "The #{name} function." %>
+
+<% end -%>
+<% if deprecated -%>
+* **DEPRECATED** <%= deprecated %>
+
+<% end -%>
+<% if todo -%>
+* **TODO** <%= todo %>
+
+<% end -%>
+<% if note -%>
+* **Note** <%= note %>
+
+<% end -%>
+<% if examples -%>
+#### Examples
+
+<% examples.each do |eg| -%>
+##### <%= eg[:name] %>
+
+```puppet
+<%= eg[:text] %>
+```
+
+<% end -%>
+<% end -%>
+<% signatures.each do |sig| -%>
+#### `<%= sig.signature %>`
+
+<% if sig.text -%>
+<%= sig.text %>
+
+<% elsif sig.summary -%>
+<%= sig.summary %>
+
+<% else -%>
+<%= "The #{name} function." %>
+
+<% end -%>
+<% if sig.note -%>
+* **Note** <%= sig.note %>
+
+<% end -%>
+<% if sig.return_type -%>
+Returns: `<%= sig.return_type %>`<% if sig.return_val %> <%= sig.return_val %><% end %>
+
+<% end -%>
+<% if raises -%>
+Raises:
+
+<% raises.each do |r| -%>
+* <%= error_type(r[:text]) %> <%= error_text(r[:text]) %>
+<% end -%>
+
+<% end -%>
+<% if sig.examples -%>
+##### Examples
+
+<% sig.examples.each do |eg| -%>
+###### <%= eg[:name] %>
+
+```puppet
+<%= eg[:text] %>
+```
+
+<% end -%>
+<% end -%>
+<% if sig.params -%>
+<% sig.params.each do |param| -%>
+##### `<%= param[:name]  %>`
+
+Data type:<%= code_maybe_block(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 -%>
+<% if sig.enums_for_param(param[:name]) -%>
+Options:
+
+<% sig.enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
+<% end -%>
+<% end -%>
+<% end -%>
+<% end -%>

data/lib/openvox-strings/markdown/templates/puppet_task.erb

@@ -0,0 +1,28 @@
+### <a name="<%= link %>"></a>`<%= name %>`
+
+<% if text -%>
+<%= text %>
+
+<% elsif summary -%>
+<%= summary %>
+
+<% else -%>
+<%= "The #{name} task." %>
+
+<% end -%>
+**Supports noop?** <%= supports_noop %>
+
+<% if params -%>
+#### Parameters
+
+<% params.each do |param| -%>
+##### `<%= param[:name] %>`
+
+<% if param[:types] -%>
+Data type:<%= code_maybe_block(param[:types].join(', ')) %>
+
+<% end -%>
+<%= param[:text] %>
+
+<% end -%>
+<% end -%>

data/lib/openvox-strings/markdown/templates/resource_type.erb

@@ -0,0 +1,156 @@
+### <a name="<%= link %>"></a>`<%= name %>`
+
+<% if text -%>
+<%= text %>
+<% elsif summary -%>
+<%= summary %>
+<% else -%>
+<%= "The #{name} type." %>
+<% end -%>
+
+<% if deprecated -%>
+* **DEPRECATED** <%= deprecated %>
+
+<% end -%>
+<% if todo -%>
+* **TODO** <%= todo %>
+
+<% end -%>
+<% if note -%>
+* **Note** <%= note %>
+
+<% end -%>
+<% if since -%>
+* **Since** <%= since %>
+
+<% end -%>
+<% 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_and_checks -%>
+#### Properties
+
+The following properties are available in the `<%= name %>` <%= @type %>.
+
+<% properties_and_checks.each do |prop| -%>
+##### `<%= prop[:name] %>`
+
+<% if prop[:values] -%>
+Valid values: `<%= prop[:values].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] %>`<%= "\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 enums_for_param(prop[:name]) -%>
+Options:
+
+<% enums_for_param(prop[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
+<% end -%>
+<% if prop[:default] -%>
+Default value:<%= code_maybe_block(prop[:default], type: :ruby) %>
+
+<% end -%>
+<% end -%>
+<% end -%>
+<% if parameters -%>
+#### Parameters
+
+The following parameters are available in the `<%= name %>` <%= @type %>.
+
+<% parameters.each do |param| -%>
+* [`<%= param[:name] %>`](#<%= param[:link] %>)
+<% end -%>
+
+<% parameters.each do |param| -%>
+##### <a name="<%= param[:link] %>"></a>`<%= param[:name] %>`
+
+<% if param[:values] -%>
+Valid values: `<%= param[:values].join('`, `') %>`
+
+<% end -%>
+<% 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 -%>
+<% if param[:description] -%>
+<%= word_wrap(param[:description]) %>
+<% end -%>
+
+<% 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 enums_for_param(param[:name]) -%>
+Options:
+
+<% enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
+<% end -%>
+<% if param[:default] -%>
+Default value: `<%= param[:default] %>`
+
+<% end -%>
+<% if param[:required_features] -%>
+Required features: <%= param[:required_features] %>.
+
+<% end -%>
+<% end -%>
+<% end -%>

data/lib/openvox-strings/markdown/templates/table_of_contents.erb

@@ -0,0 +1,26 @@
+<% unless items.empty? -%>
+### <%= group_name %>
+<% if has_public -%>
+<% if has_private # only display public heading if we have both -%>
+
+#### Public <%= group_name %>
+<% end -%>
+
+<% items.each do |item| -%>
+<% unless item[:private] -%>
+* [`<%= item[:name] %>`](#<%= item[:link] %>)<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
+<% end -%>
+<% end -%>
+<% end -%>
+<% if has_private -%>
+
+#### Private <%= group_name %>
+
+<% items.each do |item| -%>
+<% if item[:private] -%>
+* `<%= item[:name] %>`<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
+<% end -%>
+<% end -%>
+<% end -%>
+
+<% end -%>