puppet-strings 0.4.0 → 0.99.0

data/lib/puppet-strings.rb

@@ -0,0 +1,63 @@
+# The root module for Puppet Strings.
+module PuppetStrings
+  # The glob patterns used to search for files to document.
+  DEFAULT_SEARCH_PATTERNS = %w(
+    manifests/**/*.pp
+    functions/**/*.pp
+    types/**/*.pp
+    lib/**/*.rb
+  ).freeze
+
+  # Generates documentation.
+  # @param [Array<String>] search_patterns The search patterns (e.g. manifests/**/*.pp) to look for files.
+  # @param [Hash] options The options hash.
+  # @option options [Boolean] :debug Enable YARD debug output.
+  # @option options [Boolean] :backtrace Enable YARD backtraces.
+  # @option options [String] :markup The YARD markup format to use (defaults to 'markdown').
+  # @option options [String] :json Enables JSON output to the given file. If the file is nil, STDOUT is used.
+  # @option options [Array<String>] :yard_args The arguments to pass to yard.
+  # @return [void]
+  def self.generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {})
+    require 'puppet-strings/yard'
+    PuppetStrings::Yard.setup!
+
+    # Format the arguments to YARD
+    args = ['doc']
+    args << '--debug'     if options[:debug]
+    args << '--backtrace' if options[:backtrace]
+    args << "-m#{options[:markup] || 'markdown'}"
+
+    render_as_json = options.key? :json
+    json_file = nil
+    if render_as_json
+      json_file = options[:json]
+      # Disable output and prevent stats/progress when writing to STDOUT
+      args << '-n'
+      args << '-q' unless json_file
+      args << '--no-stats' unless json_file
+      args << '--no-progress' unless json_file
+    end
+
+    yard_args = options[:yard_args]
+    args += yard_args if yard_args
+    args += search_patterns
+
+    # Run YARD
+    YARD::CLI::Yardoc.run(*args)
+
+    # If outputting JSON, render the output
+    if render_as_json
+      require 'puppet-strings/json'
+      PuppetStrings::Json.render(json_file)
+    end
+  end
+
+  # Runs the YARD documentation server.
+  # @param [Array<String>] args The arguments to YARD.
+  def self.run_server(*args)
+    require 'puppet-strings/yard'
+    PuppetStrings::Yard.setup!
+
+    YARD::CLI::Server.run(*args)
+  end
+end

data/lib/puppet-strings/json.rb

@@ -0,0 +1,49 @@
+require 'json'
+
+# The module for JSON related functionality.
+module PuppetStrings::Json
+  # Renders the current YARD registry as JSON to the given file (or STDOUT if nil).
+  # @param [String] file The path to the output file to render the registry to. If nil, output will be to STDOUT.
+  # @return [void]
+  def self.render(file = nil)
+    document = {
+      puppet_classes: YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash),
+      defined_types: YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash),
+      resource_types: YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash),
+      providers: YARD::Registry.all(:puppet_provider).sort_by!(&:name).map!(&:to_hash),
+      puppet_functions: YARD::Registry.all(:puppet_function).sort_by!(&:name).map!(&:to_hash),
+      # TODO: Need Ruby documentation?
+    }
+
+    if file
+      File.open(file, 'w') do |f|
+        f.write(JSON.pretty_generate(document))
+        f.write("\n")
+      end
+    else
+      puts JSON.pretty_generate(document)
+    end
+  end
+
+  # Converts a YARD::Docstring (or String) to a docstring hash for JSON output.
+  # @param [YARD::Docstring, String] docstring The docstring to convert to a hash.
+  # @return [Hash] Returns a hash representation of the given docstring.
+  def self.docstring_to_hash(docstring)
+    hash = {}
+    hash[:text] = docstring
+    if docstring.is_a? YARD::Docstring
+      # Skip over the API tags that are public
+      tags = docstring.tags.select { |t| t.tag_name != 'api' || t.text != 'public' }.map do |t|
+        next t.to_hash if t.respond_to?(:to_hash)
+
+        tag = { tag_name: t.tag_name }
+        tag[:text] = t.text if t.text
+        tag[:types] = t.types if t.types
+        tag[:name] = t.name if t.name
+        tag
+      end
+      hash[:tags] = tags unless tags.empty?
+    end
+    hash
+  end
+end

data/lib/puppet-strings/tasks.rb

@@ -0,0 +1,10 @@
+require 'rake'
+require 'rake/tasklib'
+
+module PuppetStrings
+  # The module for Puppet Strings rake tasks.
+  module Tasks
+    require 'puppet-strings/tasks/generate.rb'
+    require 'puppet-strings/tasks/gh_pages.rb'
+  end
+end

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

@@ -0,0 +1,23 @@
+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|
+    patterns = args[:patterns]
+    patterns = patterns.split if patterns
+    patterns ||= PuppetStrings::DEFAULT_SEARCH_PATTERNS
+
+    options = {
+      debug: args[:debug] == 'true',
+      backtrace: args[:backtrace] == 'true',
+      markup: args[:markup] || 'markdown',
+    }
+
+    options[:json] = args[:json] if args.key? :json
+    options[:yard_args] = args[:yard_args].split if args.key? :yard_args
+
+    PuppetStrings.generate(patterns, options)
+  end
+end
+

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

@@ -0,0 +1,43 @@
+require 'puppet-strings/tasks'
+
+namespace :strings do
+  namespace :gh_pages do
+    desc 'Checkout the gh-pages branch for doc generation.'
+    task :checkout do
+      if Dir.exist?('doc')
+        fail "The 'doc' directory (#{File.expand_path('doc')}) is not a Git repository! Remove it and run the Rake task again." unless Dir.exist?('doc/.git')
+        Dir.chdir('doc') do
+          system 'git checkout gh-pages'
+          system 'git pull --rebase origin gh-pages'
+        end
+      else
+        git_uri = `git config --get remote.origin.url`.strip
+        fail "Could not determine the remote URL for origin: ensure the current directory is a Git repro with a remote named 'origin'." unless $?.success?
+
+        Dir.mkdir('doc')
+        Dir.chdir('doc') do
+          system 'git init'
+          system "git remote add origin #{git_uri}"
+          system 'git pull origin gh-pages'
+          system 'git checkout -b gh-pages'
+        end
+      end
+    end
+
+    desc 'Push new docs to GitHub.'
+    task :push do
+      Dir.chdir('doc') do
+        system 'git add .'
+        system "git commit -m '[strings] Generated Documentation Update'"
+        system 'git push origin gh-pages -f'
+      end
+    end
+
+    desc 'Run checkout, generate, and push tasks.'
+    task :update => [
+      :checkout,
+      :'strings:generate',
+      :push,
+    ]
+  end
+end

data/lib/puppet-strings/yard.rb

@@ -0,0 +1,96 @@
+require 'yard'
+
+# Module for YARD related functionality.
+module PuppetStrings::Yard
+  require 'puppet-strings/yard/code_objects'
+  require 'puppet-strings/yard/handlers'
+  require 'puppet-strings/yard/tags'
+  require 'puppet-strings/yard/parsers'
+
+  # Sets up YARD for use with puppet-strings.
+  # @return [void]
+  def self.setup!
+    # Register the template path
+    YARD::Templates::Engine.register_template_path(File.join(File.dirname(__FILE__), 'yard', 'templates'))
+
+    # Register the Puppet parser
+    YARD::Parser::SourceParser.register_parser_type(:puppet, PuppetStrings::Yard::Parsers::Puppet::Parser, ['pp'])
+
+    # Register our handlers
+    YARD::Handlers::Processor.register_handler_namespace(:puppet, PuppetStrings::Yard::Handlers::Puppet)
+    YARD::Handlers::Processor.register_handler_namespace(:puppet_ruby, PuppetStrings::Yard::Handlers::Ruby)
+
+    # Register the tag directives
+    PuppetStrings::Yard::Tags::ParameterDirective.register!
+    PuppetStrings::Yard::Tags::PropertyDirective.register!
+
+    # Ignore documentation on Puppet DSL calls
+    # This prevents the YARD DSL parser from emitting warnings for Puppet's Ruby DSL
+    YARD::Handlers::Ruby::DSLHandlerMethods::IGNORE_METHODS['create_function'] = true
+    YARD::Handlers::Ruby::DSLHandlerMethods::IGNORE_METHODS['newtype'] = true
+  end
+end
+
+# Monkey patch YARD::CLI::Yardoc#all_objects to return our custom code objects.
+# @private
+class YARD::CLI::Yardoc
+  def all_objects
+    YARD::Registry.all(
+      :root,
+      :module,
+      :class,
+      :puppet_class,
+      :puppet_defined_type,
+      :puppet_type,
+      :puppet_provider,
+      :puppet_function
+    )
+  end
+end
+
+# Monkey patch the stats object to return statistics for our objects.
+# This is the recommended way to add custom stats.
+# @private
+class YARD::CLI::Stats
+  def stats_for_puppet_classes
+    output 'Puppet Classes', *type_statistics_all(:puppet_class)
+  end
+
+  def stats_for_puppet_defined_types
+    output 'Puppet Defined Types', *type_statistics_all(:puppet_defined_type)
+  end
+
+  def stats_for_puppet_types
+    output 'Puppet Types', *type_statistics_all(:puppet_type)
+  end
+
+  def stats_for_puppet_providers
+    output 'Puppet Providers', *type_statistics_all(:puppet_provider)
+  end
+
+  def stats_for_puppet_functions
+    output 'Puppet Functions', *type_statistics_all(:puppet_function)
+  end
+
+  def output(name, data, undoc = nil)
+    # Monkey patch output to accommodate our larger header widths
+    @total += data if data.is_a?(Integer) && undoc
+    @undocumented += undoc if undoc.is_a?(Integer)
+    data =
+      if undoc
+        ('%5s (% 5d undocumented)' % [data, undoc])
+      else
+        '%5s' % data
+      end
+    log.puts('%-21s %s' % [name + ':', data])
+  end
+
+  # This differs from the YARD implementation in that it considers
+  # a docstring without text but with tags to be undocumented.
+  def type_statistics_all(type)
+    objs = all_objects.select {|m| m.type == type }
+    undoc = objs.find_all {|m| m.docstring.all.empty? }
+    @undoc_list |= undoc if @undoc_list
+    [objs.size, undoc.size]
+  end
+end

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

@@ -0,0 +1,8 @@
+# The module for custom YARD code objects.
+module PuppetStrings::Yard::CodeObjects
+  require 'puppet-strings/yard/code_objects/class'
+  require 'puppet-strings/yard/code_objects/defined_type'
+  require 'puppet-strings/yard/code_objects/type'
+  require 'puppet-strings/yard/code_objects/provider'
+  require 'puppet-strings/yard/code_objects/function'
+end

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

@@ -0,0 +1,14 @@
+# Implements the base code object.
+class PuppetStrings::Yard::CodeObjects::Base < YARD::CodeObjects::NamespaceObject
+  # Allocates a new code object.
+  # @param [Array] args The arguments to initialize the code object with.
+  # @return Returns the code object.
+  def self.new(*args)
+    # Skip the super class' implementation because it detects :: in names and this will cause namespaces in the output we don't want
+    object = Object.class.instance_method(:new).bind(self).call(*args)
+    existing = YARD::Registry.at(object.path)
+    object = existing if existing && existing.class == self
+    yield(object) if block_given?
+    object
+  end
+end

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

@@ -0,0 +1,59 @@
+require 'puppet-strings/yard/code_objects/group'
+
+# Implements the group for Puppet classes.
+class PuppetStrings::Yard::CodeObjects::Classes < PuppetStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_classes)
+  end
+
+  # Gets the display name of the group.
+  # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
+  # @return [String] Returns the display name of the group.
+  def name(prefix = false)
+    'Puppet Classes'
+  end
+end
+
+# Implements the Puppet class code object.
+class PuppetStrings::Yard::CodeObjects::Class < PuppetStrings::Yard::CodeObjects::Base
+  attr_reader :statement
+  attr_reader :parameters
+
+  # Initializes a Puppet class code object.
+  # @param [PuppetStrings::Parsers::ClassStatement] statement The class statement that was parsed.
+  # @return [void]
+  def initialize(statement)
+    @statement = statement
+    @parameters = statement.parameters.map { |p| [p.name, p.value] }
+    super(PuppetStrings::Yard::CodeObjects::Classes.instance, statement.name)
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_class
+  end
+
+  # Gets the source of the code object.
+  # @return Returns the source of the code object.
+  def source
+    @statement.source
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+    hash[:name] = name
+    hash[:file] = file
+    hash[:line] = line
+    hash[:inherits] = statement.parent_class if statement.parent_class
+    hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring)
+    defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten]
+    hash[:defaults] = defaults unless defaults.empty?
+    hash[:source] = source unless source && source.empty?
+    hash
+  end
+end

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

@@ -0,0 +1,58 @@
+require 'puppet-strings/yard/code_objects/group'
+
+# Implements the group for Puppet defined types.
+class PuppetStrings::Yard::CodeObjects::DefinedTypes < PuppetStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_defined_types)
+  end
+
+  # Gets the display name of the group.
+  # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
+  # @return [String] Returns the display name of the group.
+  def name(prefix = false)
+    'Defined Types'
+  end
+end
+
+# Implements the Puppet defined type code object.
+class PuppetStrings::Yard::CodeObjects::DefinedType < PuppetStrings::Yard::CodeObjects::Base
+  attr_reader :statement
+  attr_reader :parameters
+
+  # Initializes a Puppet defined type code object.
+  # @param [PuppetStrings::Parsers::DefinedTypeStatement] statement The defined type statement that was parsed.
+  # @return [void]
+  def initialize(statement)
+    @statement = statement
+    @parameters = statement.parameters.map { |p| [p.name, p.value] }
+    super(PuppetStrings::Yard::CodeObjects::DefinedTypes.instance, statement.name)
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_defined_type
+  end
+
+  # Gets the source of the code object.
+  # @return Returns the source of the code object.
+  def source
+    @statement.source
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+    hash[:name] = name
+    hash[:file] = file
+    hash[:line] = line
+    hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring)
+    defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten]
+    hash[:defaults] = defaults unless defaults.empty?
+    hash[:source] = source unless source && source.empty?
+    hash
+  end
+end

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

@@ -0,0 +1,93 @@
+require 'puppet-strings/yard/code_objects/group'
+
+# Implements the group for Puppet functions.
+class PuppetStrings::Yard::CodeObjects::Functions < PuppetStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @param [Symbol] type The function type to get the group for.
+  # @return Returns the singleton instance of the group.
+  def self.instance(type)
+    super("puppet_functions_#{type}".intern)
+  end
+
+  # Gets the display name of the group.
+  # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
+  # @return [String] Returns the display name of the group.
+  def name(prefix = false)
+    'Puppet Functions'
+  end
+end
+
+# Implements the Puppet function code object.
+class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObjects::Base
+  # Identifier for 3.x Ruby API functions
+  RUBY_3X = :ruby3x
+  # Identifier for 4.x Ruby API functions
+  RUBY_4X = :ruby4x
+  # Identifier for Puppet language functions
+  PUPPET = :puppet
+
+  attr_accessor :parameters
+
+  # Initializes a Puppet function code object.
+  # @param [String] name The name of the function.
+  # @param [Symbol] function_type The type of function (e.g. :ruby3x, :ruby4x, :puppet)
+  # @return [void]
+  def initialize(name, function_type)
+    super(PuppetStrings::Yard::CodeObjects::Functions.instance(function_type), name)
+    @parameters = []
+    @function_type = function_type
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_function
+  end
+
+  # Gets the function type display string.
+  # @return Returns the function type display string.
+  def function_type
+    case @function_type
+    when RUBY_3X
+      'Ruby 3.x API'
+    when RUBY_4X
+      'Ruby 4.x API'
+    else
+      'Puppet Language'
+    end
+  end
+
+  # Gets the Puppet signature of the function (single overload only).
+  # @return [String] Returns the Puppet signature of the function.
+  def signature
+    return '' if self.has_tag? :overload
+    tags = self.tags(:param)
+    args = @parameters.map do |parameter|
+      name, default = parameter
+      tag = tags.find { |tag| tag.name == name } if tags
+      type = tag && tag.types ? "#{tag.type} " : 'Any '
+      prefix = "#{name[0]}" if name.start_with?('*', '&')
+      name = name[1..-1] if prefix
+      default = " = #{default}" if default
+      "#{type}#{prefix}$#{name}#{default}"
+    end.join(', ')
+    @name.to_s + '(' + args + ')'
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+    hash[:name] = name
+    hash[:file] = file
+    hash[:line] = line
+    hash[:type] = @function_type.to_s
+    signature = self.signature
+    hash[:signature] = signature unless signature.empty?
+    hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring)
+    defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten]
+    hash[:defaults] = defaults unless defaults.empty?
+    hash[:source] = source unless source && source.empty?
+    hash
+  end
+end