openvox-strings 5.0.0

data/lib/openvox-strings/yard.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'yard'
+
+# Module for YARD related functionality.
+module OpenvoxStrings::Yard
+  require 'openvox-strings/yard/code_objects'
+  require 'openvox-strings/yard/handlers'
+  require 'openvox-strings/yard/tags'
+  require 'openvox-strings/yard/parsers'
+  require 'openvox-strings/monkey_patches/display_object_command'
+
+  # Sets up YARD for use with openvox-strings.
+  # @return [void]
+  def self.setup!
+    # Register our factory
+    YARD::Tags::Library.default_factory = OpenvoxStrings::Yard::Tags::Factory
+
+    # 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, OpenvoxStrings::Yard::Parsers::Puppet::Parser, ['pp'])
+    YARD::Parser::SourceParser.register_parser_type(:json, OpenvoxStrings::Yard::Parsers::JSON::Parser, ['json'])
+
+    # Register our handlers
+    YARD::Handlers::Processor.register_handler_namespace(:puppet, OpenvoxStrings::Yard::Handlers::Puppet)
+    YARD::Handlers::Processor.register_handler_namespace(:puppet_ruby, OpenvoxStrings::Yard::Handlers::Ruby)
+    YARD::Handlers::Processor.register_handler_namespace(:json, OpenvoxStrings::Yard::Handlers::JSON)
+
+    # Register the tag directives
+    OpenvoxStrings::Yard::Tags::ParameterDirective.register!
+    OpenvoxStrings::Yard::Tags::PropertyDirective.register!
+
+    # Register the summary tag
+    OpenvoxStrings::Yard::Tags::SummaryTag.register!
+
+    # Register the enum tag
+    OpenvoxStrings::Yard::Tags::EnumTag.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_data_type,
+      :puppet_data_type_alias,
+      :puppet_defined_type,
+      :puppet_type,
+      :puppet_provider,
+      :puppet_function,
+      :puppet_task,
+      :puppet_plan
+    )
+  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_data_types
+    output 'Puppet Data Types', *type_statistics_all(:puppet_data_type)
+  end
+
+  def stats_for_puppet_data_type_aliases
+    output 'Puppet Data Type Aliases', *type_statistics_all(:puppet_data_type_alias)
+  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 stats_for_puppet_tasks
+    output 'Puppet Tasks', *type_statistics_all(:puppet_task)
+  end
+
+  def stats_for_puppet_plans
+    return unless OpenvoxStrings.puppet_5?
+
+    output 'Puppet Plans', *type_statistics_all(:puppet_plan)
+  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
+        "#{data} (#{undoc} undocumented)"
+      else
+        data.to_s
+      end
+    log.puts("#{name.ljust(25)} #{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.select { |m| m.docstring.all.empty? }
+    @undoc_list |= undoc if @undoc_list
+    [objs.size, undoc.size]
+  end
+end

data/lib/openvox-strings.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# The root module for Puppet Strings.
+module OpenvoxStrings
+  # The glob patterns used to search for files to document.
+  DEFAULT_SEARCH_PATTERNS = ['manifests/**/*.pp', 'functions/**/*.pp', 'types/**/*.pp', 'lib/**/*.rb', 'tasks/*.json', 'plans/**/*.pp'].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] :path Write the selected format to a file path
+  # @option options [Boolean] :markdown From the --format option, is the format Markdown?
+  # @option options [Boolean] :json Is the format JSON?
+  # @option options [Array<String>] :yard_args The arguments to pass to yard.
+  # @return [void]
+  def self.generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {})
+    require 'openvox-strings/yard'
+    OpenvoxStrings::Yard.setup!
+
+    # Format the arguments to YARD
+    args = ['doc']
+    args << '--no-progress'
+    args << '--debug'     if options[:debug]
+    args << '--backtrace' if options[:debug]
+    args << "-m#{options[:markup] || 'markdown'}"
+
+    file = nil
+    if options[:json] || options[:markdown]
+      file = if options[:json]
+               options[:path]
+             elsif options[:markdown]
+               options[:path] || 'REFERENCE.md'
+             end
+      # Disable output and prevent stats/progress when writing to STDOUT
+      args << '-n'
+      args << '-q' unless file
+      args << '--no-stats' unless 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
+    render_json(file) if options[:json] && !options[:describe]
+
+    # If outputting Markdown, render the output
+    render_markdown(file) if options[:markdown]
+
+    return unless options[:describe]
+
+    render_describe(options[:describe_types], options[:describe_list], options[:providers], options[:list_providers])
+  end
+
+  def self.puppet_5?
+    Puppet::Util::Package.versioncmp(Puppet.version, '5.0.0') >= 0
+  end
+
+  def self.render_json(path)
+    require 'openvox-strings/json'
+    OpenvoxStrings::Json.render(path)
+  end
+
+  def self.render_markdown(path)
+    require 'openvox-strings/markdown'
+    OpenvoxStrings::Markdown.render(path)
+  end
+
+  def self.render_describe(describe_types, list = false, show_providers = true, list_providers = false)
+    require 'openvox-strings/describe'
+    OpenvoxStrings::Describe.render(describe_types, list, show_providers, list_providers)
+  end
+
+  # Runs the YARD documentation server.
+  # @param [Array<String>] args The arguments to YARD.
+  def self.run_server(*args)
+    require 'openvox-strings/yard'
+    OpenvoxStrings::Yard.setup!
+
+    YARD::CLI::Server.run(*args)
+  end
+end

data/lib/puppet/application/strings.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'puppet/application/face_base'
+
+# Implements the 'puppet strings' application.
+class Puppet::Application::Strings < Puppet::Application::FaceBase
+end

data/lib/puppet/face/strings.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'puppet/face'
+
+# Implements the 'puppet strings' interface.
+Puppet::Face.define(:strings, '0.0.1') do # rubocop:disable Metrics/BlockLength
+  summary 'Generate Puppet module documentation with YARD.'
+
+  action(:generate) do
+    default
+
+    option '--format OUTPUT_FORMAT' do
+      summary 'Designate output format, JSON or markdown.'
+    end
+    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
+
+    summary 'Generate documentation from files.'
+    arguments '[[search_pattern] ...]'
+
+    when_invoked do |*args|
+      check_required_features
+      require 'openvox-strings'
+
+      OpenvoxStrings.generate(
+        args.count > 1 ? args[0..-2] : OpenvoxStrings::DEFAULT_SEARCH_PATTERNS,
+        build_generate_options(args.last)
+      )
+      nil
+    end
+  end
+
+  action(:server) do
+    option '--markup FORMAT' do
+      summary "The markup format to use for docstring text (defaults to 'markdown')."
+    end
+
+    summary 'Runs a local documentation server for the modules in the current Puppet environment.'
+    arguments '[[module_name] ...]'
+
+    when_invoked do |*args|
+      check_required_features
+      require 'openvox-strings'
+
+      modules = args.count > 1 ? args[0..-2] : []
+
+      # Generate documentation for all (or the given) modules
+      module_docs = []
+      environment = Puppet.lookup(:current_environment)
+      environment.modules.each do |mod|
+        next unless modules.empty? || modules.include?(mod.name)
+
+        db = File.join(mod.path, '.yardoc')
+        patterns = OpenvoxStrings::DEFAULT_SEARCH_PATTERNS.map do |p|
+          File.join(mod.path, p)
+        end
+        puts "Generating documentation for Puppet module '#{mod.name}'."
+        OpenvoxStrings.generate(patterns, build_generate_options(args.last, '--db', db))
+
+        # Clear the registry so that the next call to generate has a clean database
+        YARD::Registry.clear
+
+        module_docs << mod.name
+        module_docs << db
+      end
+
+      if module_docs.empty?
+        puts 'No Puppet modules were found to serve documentation for.'
+        return
+      end
+      puts 'Starting YARD documentation server.'
+      OpenvoxStrings.run_server('-m', *module_docs)
+      nil
+    end
+  end
+
+  action(:describe) do # This is Kris' experiment with string based describe
+    option '--list' do
+      summary 'list types'
+    end
+    option '--providers' do
+      summary 'provide details on providers for each type'
+    end
+    option '--list-providers' do
+      summary 'list all providers'
+    end
+
+    # TODO: Implement the rest of describe behavior
+    #     * --help:
+    #   Print this help text
+
+    # * --providers:
+    #   Describe providers in detail for each type
+
+    # * --list:
+    #   List all types
+
+    # * --list-providers:
+    #   list all providers
+
+    # * --meta:
+    #   List all metaparameters
+
+    # * --short:
+    #   List only parameters without detail
+
+    when_invoked do |*args|
+      check_required_features
+      require 'openvox-strings'
+
+      options = args.last
+      options[:describe] = true
+      options[:stdout] = true
+      options[:format] = 'json'
+
+      if args.length > 1
+        if options[:list]
+          warn 'WARNING: ignoring types when listing all types.'
+        else
+          options[:describe_types] = args[0..-2]
+        end
+      end
+
+      # TODO: Set up search_patterns and whatever else needed to collect data for describe - currently missing some
+      #          manifests/**/*.pp
+      #          functions/**/*.pp
+      #          tasks/*.json
+      #          plans/*.pp
+      search_patterns = ['types/**/*.pp', 'lib/**/*.rb']
+      OpenvoxStrings.generate(
+        search_patterns,
+        build_generate_options(options)
+      )
+      nil
+    end
+  end
+
+  # Checks that the required features are installed.
+  # @return [void]
+  def check_required_features
+    raise "The 'yard' gem must be installed in order to use this face." unless Puppet.features.yard?
+    raise "The 'rgen' gem must be installed in order to use this face." unless Puppet.features.rgen?
+  end
+
+  # Builds the options to OpenvoxStrings.generate.
+  # @param [Hash] options The Puppet face options hash.
+  # @param [Array] yard_args The additional arguments to pass to YARD.
+  # @return [Hash] Returns the OpenvoxStrings.generate options hash.
+  def build_generate_options(options = nil, *yard_args)
+    generate_options = {}
+    generate_options[:debug] = Puppet[:debug]
+    generate_options[:backtrace] = Puppet[:trace]
+    generate_options[:yard_args] = yard_args unless yard_args.empty?
+    if options
+      markup = options[:markup]
+      generate_options[:markup] = markup if markup
+      generate_options[:path] = options[:out] if options[:out]
+      generate_options[:stdout] = options[:stdout]
+
+      if options[:describe]
+        generate_options[:describe] = true
+        generate_options[:describe_types] = options[:describe_types]
+        generate_options[:describe_list] = options[:list]
+        generate_options[:providers] = options[:providers]
+        generate_options[:list_providers] = options[:list_providers]
+      end
+
+      format = options[:format]
+      if format
+        if format.casecmp('markdown').zero?
+          generate_options[:markdown] = true
+        elsif format.casecmp('json').zero?
+          generate_options[:json] = true
+        else
+          raise "Invalid format #{options[:format]}. Please select 'json' or 'markdown'."
+        end
+      end
+    end
+    generate_options
+  end
+end

data/lib/puppet/feature/rgen.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'puppet/util/feature'
+
+Puppet.features.add(:rgen, libs: ['rgen/metamodel_builder', 'rgen/ecore/ecore'])

data/lib/puppet/feature/yard.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'puppet/util/feature'
+
+Puppet.features.add(:yard, libs: ['yard'])