puppet-strings 1.1.1 → 1.2.0

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

@@ -0,0 +1,21 @@
+<% 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] %>
+<% end -%>
+<% end -%>
+<% else -%>
+<% group.each do |item| -%>
+* [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %>
+<% end -%>
+<% end -%>
+<% end -%>

data/lib/puppet-strings/tasks/generate.rb

@@ -3,7 +3,7 @@ require 'puppet-strings'
 # Implements the strings:generate task.
 namespace :strings do
   desc 'Generate Puppet documentation with YARD.'
-  task :generate, :patterns, :debug, :backtrace, :markup, :json, :yard_args do |t, args|
+  task :generate, [:patterns, :debug, :backtrace, :markup, :json, :markdown, :yard_args] do |t, args|
     patterns = args[:patterns]
     patterns = patterns.split if patterns
     patterns ||= PuppetStrings::DEFAULT_SEARCH_PATTERNS
@@ -14,11 +14,30 @@ namespace :strings do
       markup: args[:markup] || 'markdown',
     }
 
-	# rubocop:disable Style/PreferredHashMethods
-	# `args` is a Rake::TaskArguments and has no key? method
-    options[:json] = args[:json] if args.has_key? :json
+    raise("Error: Both JSON and Markdown output have been selected. Please select one.") if args[:json] == 'true' && args[:markdown] == 'true'
+
+    # rubocop:disable Style/PreferredHashMethods
+    # Because of Ruby, true and false from the args are both strings and both true. Here,
+    # when the arg is set to false (or empty), set it to real false, else real true. Then,
+    # if the arg is set simply to 'true', assume default behavior is expected and set the path
+    # to nil to elicit that, else set to the path given.
+    # @param [Hash] args from the Rake task cli
+    # @param [Hash] options to send to the generate function
+    # @param [Symbol] possible format option
+    # @return nil
+    def parse_format_option(args, options, format)
+      if args.has_key? format
+        options[format] = args[format] == 'false' || args[format].empty? ? false : true
+        if options[format]
+          options[:path] = args[format] == 'true' ? nil : args[format]
+        end
+      end
+    end
+
+    [:json,:markdown].each { |format| parse_format_option(args, options, format) }
+
+    warn('yard_args behavior is a little dodgy, use at your own risk') if args[:yard_args]
     options[:yard_args] = args[:yard_args].split if args.has_key? :yard_args
-	# rubocop:enable Style/PreferredHashMethods
 
     PuppetStrings.generate(patterns, options)
   end

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

@@ -84,14 +84,14 @@ class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObje
     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)

data/lib/puppet-strings/yard/code_objects/type.rb

@@ -22,7 +22,7 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
   # Represents a resource type parameter.
   class Parameter
     attr_reader :name, :values, :aliases
-    attr_accessor :docstring, :isnamevar, :default
+    attr_accessor :docstring, :isnamevar, :default, :data_type
 
     # Initializes a resource type parameter or property.
     # @param [String] name The name of the parameter or property.
@@ -31,6 +31,7 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
       @name = name
       @docstring = docstring || ''
       @values = []
+      @data_type = []
       @aliases = {}
       @isnamevar = false
       @default = nil
@@ -59,6 +60,7 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
       hash[:name] = name
       hash[:description] = docstring unless docstring.empty?
       hash[:values] = values unless values.empty?
+      hash[:data_type] = data_type unless data_type.empty?
       hash[:aliases] = aliases unless aliases.empty?
       hash[:isnamevar] = true if isnamevar
       hash[:default] = default if default

data/lib/puppet-strings/yard/handlers.rb

@@ -3,6 +3,7 @@ module PuppetStrings::Yard::Handlers
   # The module for custom Ruby YARD handlers.
   module Ruby
     require 'puppet-strings/yard/handlers/ruby/type_handler'
+    require 'puppet-strings/yard/handlers/ruby/rsapi_handler'
     require 'puppet-strings/yard/handlers/ruby/provider_handler'
     require 'puppet-strings/yard/handlers/ruby/function_handler'
   end

data/lib/puppet-strings/yard/handlers/puppet/function_handler.rb

@@ -37,7 +37,7 @@ class PuppetStrings::Yard::Handlers::Puppet::FunctionHandler < PuppetStrings::Ya
   def add_return_tag(object, type=nil)
     tag = object.tag(:return)
     if tag
-      if (type && tag.types) && (type != tag.types)
+      if (type && tag.types.first) && (type != tag.types.first)
         log.warn "Documented return type does not match return type in function definition near #{statement.file}:#{statement.line}."
       end
 

data/lib/puppet-strings/yard/handlers/ruby/base.rb

@@ -29,7 +29,7 @@ class PuppetStrings::Yard::Handlers::Ruby::Base < YARD::Handlers::Ruby::Base
       source = node.source
       if source =~ HEREDOC_START
         lines = source.split("\n")
-        source = lines[1..(lines.last.include?($1) ? -2 : -1)].join("\n") if lines.size > 1
+        source = lines[1..(lines.last.include?($1[0..-2]) ? -2 : -1)].join("\n") if lines.size > 1
       end
 
       source

data/lib/puppet-strings/yard/handlers/ruby/rsapi_handler.rb

@@ -0,0 +1,141 @@
+require 'puppet-strings/yard/handlers/helpers'
+require 'puppet-strings/yard/handlers/ruby/base'
+require 'puppet-strings/yard/code_objects'
+require 'puppet-strings/yard/util'
+
+# Implements the handler for Puppet resource types written in Ruby.
+class PuppetStrings::Yard::Handlers::Ruby::RsapiHandler < PuppetStrings::Yard::Handlers::Ruby::Base
+  # The default docstring when ensurable is used without given a docstring.
+  DEFAULT_ENSURABLE_DOCSTRING = 'The basic property that the resource should be in.'.freeze
+
+  namespace_only
+  handles method_call(:register_type)
+
+  process do
+    # Only accept calls to Puppet::ResourceApi
+    return unless statement.count > 1
+    module_name = statement[0].source
+    return unless [ 'Puppet::ResourceApi' ].include? module_name
+
+    schema = extract_schema
+
+    # puts "Schema: #{schema.inspect}"
+
+    object = PuppetStrings::Yard::CodeObjects::Type.new(schema['name'])
+    register object
+
+    docstring = schema['desc'] || ""
+    if docstring
+      register_docstring(object, PuppetStrings::Yard::Util.scrub_string(docstring.to_s), nil)
+    else
+      log.warn "Missing a description for Puppet resource type '#{object.name}' at #{statement.file}:#{statement.line}."
+    end
+
+    # Populate the parameters/properties/features to the type
+    populate_type_data(object, schema)
+
+    # Mark the type as public if it doesn't already have an api tag
+    object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api
+
+    # Warn if a summary longer than 140 characters was provided
+    PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
+  end
+
+  private
+
+  def raise_parse_error(msg, location = statement)
+    raise YARD::Parser::UndocumentableError, "#{msg} at #{location.file}:#{location.line}." if parameters.empty?
+  end
+
+  # check that the params of the register_type call are key/value pairs.
+  def kv_arg_list?(params)
+    params.type == :list && params.children.count > 0 && params.children.first.type == :list && params.children.first.children.count > 0 && statement.parameters.children.first.children.first.type == :assoc
+  end
+
+  def extract_schema
+    raise_parse_error("Expected list of key/value pairs as argument") unless kv_arg_list?(statement.parameters)
+    hash_from_node(statement.parameters.children.first)
+  end
+
+  def value_from_node(node)
+    return nil unless node
+
+    # puts "value from #{node.inspect}"
+
+    case node.type
+    when :int
+      node.source.to_i
+    when :hash
+      hash_from_node(node)
+    when :var_ref
+      var_ref_from_node(node)
+    when :symbol, :symbol_literal, :label, :dyna_symbol, :string_literal
+      node_as_string(node)
+    else
+      raise_parse_error("unexpected construct #{node.type}")
+    end
+  end
+
+  def hash_from_node(node)
+    return nil unless node
+
+    # puts "hash from #{node.inspect}"
+
+    kv_pairs = node.children.collect do |assoc|
+      [ value_from_node(assoc.children[0]), value_from_node(assoc.children[1]) ]
+    end
+    Hash[kv_pairs]
+  end
+
+  def var_ref_from_node(node)
+    return nil unless node
+
+    # puts "var_ref from #{node.inspect}"
+
+    if node.children.first.type == :kw
+      case node.children.first.source
+      when "false"
+        return false
+      when "true"
+        return true
+      when "nil"
+        return nil
+      else
+        raise_parse_error("unexpected keyword '#{node.children.first.source}'")
+      end
+    end
+    raise_parse_error("unexpected variable")
+  end
+
+
+  def populate_type_data(object, schema)
+    return if schema['attributes'].nil?
+
+    schema['attributes'].each do |name, definition|
+      # puts "Processing #{name}: #{definition.inspect}"
+      if ['parameter', 'namevar'].include? definition['behaviour']
+        object.add_parameter(create_parameter(name, definition))
+      else
+        object.add_property(create_property(name, definition))
+      end
+    end
+  end
+
+  def create_parameter(name, definition)
+    parameter = PuppetStrings::Yard::CodeObjects::Type::Parameter.new(name, definition['desc'])
+    set_values(definition, parameter)
+    parameter
+  end
+
+  def create_property(name, definition)
+    property = PuppetStrings::Yard::CodeObjects::Type::Property.new(name, definition['desc'])
+    set_values(definition, property)
+    property
+  end
+
+  def set_values(definition, object)
+    object.data_type = definition['type'] if definition.key? 'type'
+    object.default = definition['default'] if definition.key? 'default'
+    object.isnamevar = definition.key?('behaviour') && definition['behaviour'] == 'namevar'
+  end
+end

data/lib/puppet/face/strings.rb

@@ -7,15 +7,21 @@ Puppet::Face.define(:strings, '0.0.1') do
   action(:generate) do
     default
 
-    option '--emit-json-stdout' do
-      summary 'Print JSON representation of the documentation to stdout.'
+    option '--format OUTPUT_FORMAT' do
+      summary 'Designate output format, JSON or markdown.'
     end
-    option '--emit-json FILE' do
-      summary 'Write JSON representation of the documentation to the given file.'
+    option '--out PATH' do
+      summary 'Write selected format to PATH. If no path is designated, strings prints to STDOUT.'
     end
     option '--markup FORMAT' do
       summary "The markup format to use for docstring text (defaults to 'markdown')."
     end
+    option '--emit-json-stdout' do
+      summary 'DEPRECATED: Print JSON representation of the documentation to stdout.'
+    end
+    option '--emit-json PATH' do
+      summary 'DEPRECATED: Write JSON representation of the documentation to the given file.'
+    end
 
     summary 'Generate documentation from files.'
     arguments '[[search_pattern] ...]'
@@ -94,11 +100,26 @@ Puppet::Face.define(:strings, '0.0.1') do
     generate_options[:yard_args] = yard_args unless yard_args.empty?
 
     if options
+      if options[:emit_json]
+        $stderr.puts "WARNING: '--emit-json PATH' is deprecated. Use '--format json --out PATH' instead."
+      end
+      if options[:emit_json_stdout]
+        $stderr.puts "WARNING: '--emit-json-stdout' is deprecated. Use '--format json' instead."
+      end
       markup = options[:markup]
       generate_options[:markup] = markup if markup
-      json_file = options[:emit_json]
-      generate_options[:json] = json_file if json_file
-      generate_options[:json] = nil if options[:emit_json_stdout]
+      generate_options[:path] = options[:out] if options[:out]
+      generate_options[:stdout] = options[:stdout]
+      format = options[:format]
+      if format
+        if format.casecmp('markdown').zero?
+          generate_options[:markdown] = true
+        elsif format.casecmp('json').zero? || options[:emit_json] || options[:emit_json_stdout]
+          generate_options[:json] = true
+        else
+          raise RuntimeError, "Invalid format #{options[:format]}. Please select 'json' or 'markdown'."
+        end
+      end
     end
     generate_options
   end

data/spec/acceptance/emit_json_options.rb

@@ -37,18 +37,18 @@ describe 'Emitting JSON' do
     ]
   }
 
-  it 'should emit JSON to stdout when using the --emit-json-stdout option' do
+  it 'should emit JSON to stdout when using --format json and --stdout' do
     test_module_path = get_test_module_path(master, /Module test/)
-    on master, puppet('strings', 'generate', '--emit-json-stdout', "#{test_module_path}/lib/puppet/parser/functions/function3x.rb") do
+    on master, puppet('strings', 'generate', '--format json', "#{test_module_path}/lib/puppet/parser/functions/function3x.rb") do
       output = stdout.chomp
       expect(JSON.parse(output)).to eq(expected)
     end
   end
 
-  it 'should write JSON to a file when using the --emit-json option' do
+  it 'should write JSON to a file when using --format json and --out' do
     test_module_path = get_test_module_path(master, /Module test/)
     tmpfile = master.tmpfile('json_output.json')
-    on master, puppet('strings', 'generate', "--emit-json #{tmpfile}", "#{test_module_path}/lib/puppet/parser/functions/function3x.rb")
+    on master, puppet('strings', 'generate', '--format json', "--out #{tmpfile}", "#{test_module_path}/lib/puppet/parser/functions/function3x.rb")
     output = read_file_on(master, tmpfile)
     expect(JSON.parse(output)).to eq(expected)
   end

data/spec/acceptance/generate_markdown_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper_acceptance'
+require 'util'
+
+include PuppetStrings::Acceptance::Util
+
+describe 'Generating Markdown' do
+  expected = <<-EOF
+# Reference
+
+## Classes
+* [`test`](#test): This class exists to serve as fixture data for testing the puppet strings face
+
+## Classes
+
+### test
+
+#### Examples
+```puppet
+class { "test": }
+```
+
+#### Parameters
+
+##### `package_name`
+
+The name of the package
+
+##### `service_name`
+
+The name of the service
+
+EOF
+
+  it 'should render Markdown to stdout when using --format markdown and --stdout' do
+    test_module_path = get_test_module_path(master, /Module test/)
+    on master, puppet('strings', 'generate', '--format markdown', "#{test_module_path}/manifests/init.pp") do
+      output = stdout.chomp
+      expect(JSON.parse(output)).to eq(expected)
+    end
+  end
+
+  it 'should write Markdown to a file when using --format markdown and --out' do
+    test_module_path = get_test_module_path(master, /Module test/)
+    tmpfile = master.tmpfile('md_output.md')
+    on master, puppet('strings', 'generate', '--format markdown', "--out #{tmpfile}", "#{test_module_path}/manifests/init.pp")
+    output = read_file_on(master, tmpfile)
+    expect(JSON.parse(output)).to eq(expected)
+  end
+end

data/spec/fixtures/unit/json/output.json

@@ -81,6 +81,49 @@
     }
   ],
   "resource_types": [
+    {
+      "name": "apt_key",
+      "file": "(stdin)",
+      "line": 92,
+      "docstring": {
+        "text": "This type provides Puppet with the capabilities to manage GPG keys needed\nby apt to perform package validation. Apt has it's own GPG keyring that can\nbe manipulated through the `apt-key` command.\n**Autorequires**:\nIf Puppet is given the location of a key file which looks like an absolute\npath this type will autorequire that file.",
+        "tags": [
+          {
+            "tag_name": "summary",
+            "text": "Example resource type using the new API."
+          },
+          {
+            "tag_name": "raise",
+            "text": "SomeError"
+          },
+          {
+            "tag_name": "example",
+            "text": "apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':\n  source => 'http://apt.puppetlabs.com/pubkey.gpg'\n}",
+            "name": "here's an example"
+          }
+        ]
+      },
+      "properties": [
+        {
+          "name": "ensure",
+          "description": "Whether this apt key should be present or absent on the target system.",
+          "data_type": "Enum[present, absent]"
+        },
+        {
+          "name": "created",
+          "description": "Date the key was created, in ISO format.",
+          "data_type": "String"
+        }
+      ],
+      "parameters": [
+        {
+          "name": "id",
+          "description": "The ID of the key you want to manage.",
+          "data_type": "Variant[Pattern[/A(0x)?[0-9a-fA-F]{8}Z/], Pattern[/A(0x)?[0-9a-fA-F]{16}Z/], Pattern[/A(0x)?[0-9a-fA-F]{40}Z/]]",
+          "isnamevar": true
+        }
+      ]
+    },
     {
       "name": "database",
       "file": "(stdin)",