yard-sketchup 1.0.0

data/lib/yard-sketchup/templates/default/module/html/method_summary.erb

@@ -0,0 +1,18 @@
+<% if method_listing.size > 0 %>
+  <% groups(method_listing) do |list, name| %>
+    <h2>
+      <%= name %>
+      <a
+          id="<%= name.gsub(' ', '_').downcase %>"
+          href="#<%= name.gsub(' ', '_').downcase %>"
+          title="Permalink">#</a>
+      <small><a href="#" class="summary_toggle">collapse</a></small>
+    </h2>
+
+    <ul class="summary">
+      <% list.each do |meth| %>
+        <%= yieldall :item => meth %>
+      <% end %>
+    </ul>
+  <% end %>
+<% end %>

data/lib/yard-sketchup/templates/rubocop-changelog/fulldoc/text/setup.rb

@@ -0,0 +1,75 @@
+require 'fileutils'
+require 'set'
+require 'stringio'
+
+include Helpers::ModuleHelper
+
+def init
+  generate_changelog
+end
+
+
+def all_objects
+  run_verifier(Registry.all())
+end
+
+def namespace_objects
+  run_verifier(Registry.all(:class, :module))
+end
+
+
+def changelog_filename
+  'Changelog SU201x.log'
+end
+
+VERSION_MATCH = /^\D+([0-9.]+)(?:\s+M(\d+))?$/
+
+def generate_changelog
+  output = StringIO.new
+
+  versions = Hash.new
+  all_objects.each { |object|
+    version_tag = object.tag(:version)
+    next if version_tag.nil?
+    version = version_tag.text
+
+    # Don't list SU6 or older.
+    next if version.match(VERSION_MATCH).captures[0].to_i <= 6
+
+    versions[version] ||= {}
+    versions[version][object.type] ||= []
+    versions[version][object.type] << object.path
+  }
+  versions = versions.sort { |a, b|
+    v1, mv1 = a[0].match(VERSION_MATCH).captures
+    v2, mv2 = b[0].match(VERSION_MATCH).captures
+    if v1 == v2
+      (mv2 || '0').to_i <=> (mv1 || '0').to_i
+    else
+      v2.to_f <=> v1.to_f
+    end
+  }
+
+  output.puts "FEATURES = ["
+  versions.each { |version, features|
+    output.puts ""
+    output.puts "  {"
+    output.puts "    version: '#{version}',"
+    output.puts "    types: {"
+    features.sort.each { |type, objects|
+      unless objects.empty?
+        output.puts "      #{type}: ["
+        objects.sort.each { |object|
+          output.puts "        '#{object}',"
+        }
+        output.puts "      ],"
+      end
+    }
+    output.puts "    },"
+    output.puts "  },"
+  }
+  output.puts "]"
+
+  puts output.string
+  exit # Avoid the YARD summary
+end

data/lib/yard-sketchup/templates/stubs/fulldoc/text/setup.rb

@@ -0,0 +1,363 @@
+require 'fileutils'
+require 'pathname'
+require 'set'
+require 'stringio'
+
+include Helpers::ModuleHelper
+
+def init
+  generate_stubs
+end
+
+
+# NOTE: Remember to run objects outputted through `run_verifier` first in order
+# to filter out items that should be excluded by command line arguments.
+
+def namespace_objects
+  run_verifier(Registry.all(:class, :module))
+end
+
+
+def generate_autoload
+  generate_sketchup_autoload
+end
+
+def generate_sketchup_autoload
+  base = Pathname.new(autoload_stubs_path)
+  autoload_file = File.join(autoload_stubs_path, 'sketchup.rb')
+  File.open(autoload_file, 'w') { |file|
+    pattern = File.join(sketchup_stubs_path, '**/*.rb')
+    Dir.glob(pattern) { |filename|
+      pathname = Pathname.new(filename)
+      relative = pathname.relative_path_from(base)
+      file.puts "require '#{relative.to_s}'"
+    }
+  }
+end
+
+def generate_stubs
+  puts "Generating stubs..."
+  generate_module_stubs(Registry.root)
+  namespace_objects.each do |object|
+    generate_module_stubs(object)
+  end
+  generate_autoload
+end
+
+def print_section(io, title, content)
+  return if content.strip.empty?
+  io.puts
+  io.puts "  # #{title}"
+  io.puts
+  io.puts content
+end
+
+def generate_module_stubs(object)
+  filename = stub_filename(object)
+  ensure_exist(File.dirname(filename))
+  StubFile.open(filename, 'w') { |file|
+    file.puts file_header(object)
+    file.puts
+    file.puts namespace_definition(object)
+    print_section(file, 'Extends', generate_mixins(object, :class))
+    print_section(file, 'Includes', generate_mixins(object, :instance))
+    print_section(file, 'Constants', generate_constants_grouped(object))
+    print_section(file, 'Class Methods', generate_class_methods(object))
+    print_section(file, 'Instance Methods', generate_instance_methods(object))
+    file.puts
+    file.puts file_footer(object)
+  }
+  #trim_trailing_white_space(filename)
+end
+
+def file_header(object)
+  header = StringIO.new
+  header.puts "# Copyright:: Copyright #{Time.now.year} Trimble Inc."
+  header.puts "# License:: The MIT License (MIT)"
+  #header.puts "# Generated:: #{Time.now.strftime('%F %R')}"
+  header.string
+end
+
+def file_footer(object)
+  return if object.root?
+  footer = StringIO.new
+  footer.puts 'end'
+  footer.string
+end
+
+def namespace_definition(object)
+  return if object.root?
+  definition = "#{object.type} #{object.path}"
+  if object.type == :class && object.superclass.name != :Object
+    definition << " < #{object.superclass.path}"
+  end
+  output = StringIO.new
+  output.puts generate_docstring(object)
+  output.puts definition
+  output.string
+end
+
+def output_path
+  options.serializer.options[:basepath] || File.join(Dir.pwd, 'stubs')
+end
+
+def stubs_path
+  ensure_exist(output_path)
+end
+
+def autoload_stubs_path
+  ensure_exist(File.join(stubs_path, 'autoload'))
+end
+
+def sketchup_stubs_path
+  ensure_exist(File.join(stubs_path, 'SketchUp'))
+end
+
+def stub_filename(object)
+  basename = object.path.gsub('::', '/')
+  basename = '_top_level' if basename.empty?
+  File.join(sketchup_stubs_path, "#{basename}.rb")
+end
+
+CAMELCASE_CONSTANT = /^([A-Z]+[a-z]+)/
+
+def group_constant(constant)
+  constant_name = constant.name.to_s
+  MANUAL_CONSTANT_GROUPS.each { |rule|
+    if rule[:constants]
+      return rule[:group] if rule[:constants].include?(constant_name)
+    else
+      return rule[:group] if rule[:regex].match(constant_name)
+    end
+  }
+  if constant_name.include?('_')
+    constant_name.split('_').first
+  else
+    constant_name[CAMELCASE_CONSTANT] || constant_name
+  end
+end
+
+# Sorts and groups constants for easier reading.
+def generate_constants_grouped(object)
+  constants = run_verifier(object.constants(object_options))
+  # The constants are not sorted before chunking. This is because `chunk` groups
+  # consecutive items - and we want to chunk them based their relationship
+  # with each other. This ensure that constants that doesn't follow the normal
+  # pattern of PREFIX_SOME_NAME will still be grouped next to each other.
+  groups = constants.chunk { |constant|
+    group_constant(constant)
+  }
+  grouped_output = groups.map { |group, group_constants|
+    output = StringIO.new
+    # Each group itself is sorted in order to more easily scan the list.
+    sorted = group_constants.sort { |a, b|
+      a.name <=> b.name
+    }
+    sorted.each { |constant|
+      output.puts "  #{constant.name} = nil # Stub value."
+    }
+    output.string
+  }
+  # Finally each group is also sorted, again to ease scanning for a particular
+  # name. We simply use the first character of each group.
+  grouped_output.sort { |a, b|
+    a.lstrip[0] <=> b.lstrip[0]
+  }.join("\n")
+end
+
+# Sort constants without grouping.
+def generate_constants(object)
+  output = StringIO.new
+  constants = run_verifier(object.constants(object_options)).sort { |a, b|
+    a.name <=> b.name
+  }
+  constants.each { |constant|
+    output.puts "  #{constant.name} = nil # Stub value."
+  }
+  output.string
+end
+
+def generate_mixins(object, scope)
+  output = StringIO.new
+  mixin_type = (scope == :class) ? 'extend' : 'include'
+  mixins = run_verifier(object.mixins(scope)).sort { |a, b|
+    a.path <=> b.path
+  }
+  mixins.each { |mixin|
+    output.puts "  #{mixin_type} #{mixin.path}"
+  }
+  output.string
+end
+
+def generate_class_methods(object)
+  generate_methods(object, :class, 'self.')
+end
+
+def generate_instance_methods(object)
+  generate_methods(object, :instance)
+end
+
+def generate_methods(object, scope, prefix = '')
+  methods = sort_methods(object, scope)
+  signatures = methods.map { |method|
+    output = StringIO.new
+    # Cannot use `methods.signature` here as it would return the C/C++ function
+    # signature. Must generate one from the YARD data.
+    signature = generate_method_signature(method)
+    # NOTE: We must call `generate_docstring` after `generate_method_signature`
+    # because `generate_method_signature` will also clean up docstrings with
+    # a single @overload tag.
+    output.puts generate_docstring(method, 1)
+    output.puts "  def #{prefix}#{signature}"
+    output.puts "  end"
+    output.string
+  }
+  signatures.join("\n")
+end
+
+# NOTE: This may modify the docstring of the object.
+def generate_method_signature(object)
+  signature = "#{object.name}"
+  # If there is a single overload then use that as the parameter list. Many of
+  # the SketchUp Ruby API methods will have this as it was safer to add an
+  # @overload tag instead of renaming the function argument names.
+  overloads = object.docstring.tags(:overload)
+  if overloads.size == 1
+    overload = overloads.first
+    parameters = overload.parameters
+    # Move the tags from the @overload tag to the root of the docstring. No need
+    # for a single overload tag - it's unexpected when reading the source.
+    object.docstring.add_tag(*overload.tags)
+    object.docstring.delete_tags(:overload)
+  else
+    parameters = object.parameters
+  end
+  # Compile the signature for the arguments and default values.
+  params = parameters.map { |param|
+    param.last.nil? ? param.first : param.join(' = ')
+  }.join(', ')
+  signature << "(#{params})" unless params.empty?
+  signature
+end
+
+def generate_docstring(object, indent_step = 0)
+  output = StringIO.new
+  indent = '  ' * indent_step
+  docstring = object.docstring
+  docstring.delete_tags(:par) # Remove obsolete @par tags.
+  docstring.to_raw.lines.each { |line|
+    # Naive check for tags with no indent - if it is we insert an extra line
+    # in order to get some space for easier reader. Doing it this way in order
+    # to avoid hacking YARD too much.
+    output.puts "#{indent}#" if line.start_with?('@')
+    # This is the original docstring line.
+    output.puts "#{indent}# #{line}"
+  }
+  output.string
+end
+
+def sort_methods(object, scope)
+  methods = run_verifier(object.meths(object_options))
+  objects = methods.select { |method|
+    method.scope == scope
+  }
+  objects.sort { |a, b|
+    a.name <=> b.name
+  }
+end
+
+def object_options
+  {
+    :inherited => false,
+    :included => false
+  }
+end
+
+
+def ensure_exist(path)
+  unless File.directory?(path)
+    FileUtils.mkdir_p(path)
+  end
+  path
+end
+
+
+class StubFile < File
+
+  def puts(*args)
+    case args.size
+    when 0
+      super
+    when 1
+      super trim_trailing_white_space(args[0].to_s)
+    else
+      raise NotImplementedError
+    end
+  end
+
+  private
+
+  TRAILING_WHITE_SPACE = /([\t ]+)$/
+  def trim_trailing_white_space(string)
+    string.gsub(TRAILING_WHITE_SPACE, '')
+  end
+
+end
+
+
+MANUAL_CONSTANT_GROUPS = [
+  # UI.messagebox return values.
+  {
+    constants: %w{IDABORT IDCANCEL IDIGNORE IDNO IDOK IDRETRY IDYES},
+    group: 'ID_MESSAGEBOX'
+  },
+  # Axes
+  {
+    constants: %w{X_AXIS Y_AXIS Z_AXIS},
+    group: 'AXES'
+  },
+  # Axes 2D
+  {
+    constants: %w{X_AXIS_2D Y_AXIS_2D},
+    group: 'AXES2D'
+  },
+  # Transformation
+  {
+    constants: %w{IDENTITY IDENTITY_2D},
+    group: 'IDENTITY'
+  },
+  # Geom::PolygonMesh
+  {
+    constants: %w{
+      AUTO_SOFTEN HIDE_BASED_ON_INDEX NO_SMOOTH_OR_HIDE SMOOTH_SOFT_EDGES
+      SOFTEN_BASED_ON_INDEX},
+    group: 'SOFTEN'
+  },
+  # Sketchup::Importer
+  # The other constants start with Import, this was odd one out.
+  {
+    constants: %w{ImporterNotFound},
+    group: 'Import'
+  },
+  # Sketchup::Http
+  {
+    constants: %w{DELETE GET HEAD OPTIONS PATCH POST PUT},
+    group: 'HTTP'
+  },
+  # Sketchup::Licensing
+  {
+    constants: %w{EXPIRED LICENSED NOT_LICENSED TRIAL TRIAL_EXPIRED},
+    group: 'EX_LICENSE'
+  },
+  # Sketchup::Model
+  {
+    constants: %w{Make MakeTrial ProLicensed ProTrial},
+    group: 'SU_LICENSE'
+  },
+  # Sketchup::RenderingOptions
+  # Most ROP constants start with ROPSet, with a handful of exceptions.
+  {
+    regex: /^ROP/,
+    group: 'ROP'
+  },
+]

data/lib/yard-sketchup/templates/versions/fulldoc/text/setup.rb

@@ -0,0 +1,25 @@
+require 'set'
+
+include Helpers::ModuleHelper
+
+MANIFEST_FILENAME = 'coverage.manifest'.freeze
+
+def init
+  find_all_versions
+end
+
+
+def all_objects
+  run_verifier(Registry.all)
+end
+
+
+def find_all_versions
+  versions = Set.new
+  all_objects.each { |object|
+    version_tag = object.tag(:version)
+    versions << version_tag.text if version_tag
+  }
+  puts versions.sort.join("\n")
+  exit # Avoid the YARD summary
+end

data/lib/yard-sketchup/version.rb

@@ -0,0 +1,3 @@
+module SketchUpYARD
+  VERSION = '1.0.0'.freeze
+end

data/lib/yard-sketchup/yard/handlers/class_constants.rb

@@ -0,0 +1,17 @@
+module SketchUpYARD
+  class ClassConstantHandler < YARD::Handlers::C::Base
+
+    MATCH = %r{\bDEFINE_RUBY_CLASS_CONSTANT\s*\(([^,]+)\s*,\s*([^,]+)\s*,\s*(\w+)\s*\)\s*;}xm
+    handles MATCH
+    statement_class BodyStatement
+
+    process do
+      statement.source.scan(MATCH) do |klass_name, value, const_name|
+        type = "const"
+        value = "nil"
+        handle_constants(type, klass_name, const_name, value)
+      end
+    end
+
+  end
+end

data/lib/yard-sketchup/yard/handlers/class_enum_constants.rb

@@ -0,0 +1,17 @@
+module SketchUpYARD
+  class ClassEnumConstantHandler < YARD::Handlers::C::Base
+
+    MATCH = %r{\bDEFINE_RUBY_CLASS_ENUM\s*\(([^,]+)\s*,\s*(\w+)\s*\)\s*;}xm
+    handles MATCH
+    statement_class BodyStatement
+
+    process do
+      statement.source.scan(MATCH) do |klass_name, const_name|
+        type = "const"
+        value = "nil"
+        handle_constants(type, klass_name, const_name, value)
+      end
+    end
+
+  end
+end

data/lib/yard-sketchup/yard/handlers/global_constants.rb

@@ -0,0 +1,19 @@
+module SketchUpYARD
+  class GlobalConstantHandler < YARD::Handlers::C::Base
+
+    MATCH = %r{\bDEFINE_RUBY_(?:(?:NAMED_)?CONSTANT|ENUM)\s*\((?:[^)]+,\s*)?(\w+)\)\s*;}xm
+    handles MATCH
+    statement_class BodyStatement
+
+    process do
+      statement.source.scan(MATCH) do |captures|
+        const_name = captures.first
+        type = "global_const"
+        var_name = nil
+        value = "nil"
+        handle_constants(type, var_name, const_name, value)
+      end
+    end
+
+  end
+end

data/lib/yard-sketchup/yard/logger.rb

@@ -0,0 +1,45 @@
+require 'yard/logging'
+
+# Hack to show some progress on Windows while building the docs.
+# Helpful in seeing what takes most time.
+# It's Copy+Paste from YARD 0.9.9 with some noted edits.
+module YARD
+  class Logger < ::Logger
+
+    def show_progress
+      return false if YARD.ruby18? # threading is too ineffective for progress support
+      # <hack>
+      # return false if YARD.windows? # windows has poor ANSI support
+      # </hack>
+      return false unless io.tty? # no TTY support on IO
+      return false unless level > INFO # no progress in verbose/debug modes
+      @show_progress
+    end
+
+    def progress(msg, nontty_log = :debug)
+      send(nontty_log, msg) if nontty_log
+      return unless show_progress
+      icon = ""
+      if defined?(::Encoding)
+        icon = PROGRESS_INDICATORS[@progress_indicator] + " "
+      end
+      @mutex.synchronize do
+        print("\e[2K\e[?25l\e[1m#{icon}#{msg}\e[0m\r")
+        @progress_msg = msg
+        if Time.now - @progress_last_update > 0.2
+          @progress_indicator += 1
+          @progress_indicator %= PROGRESS_INDICATORS.size
+          @progress_last_update = Time.now
+        end
+      end
+      Thread.new do
+        sleep(0.05)
+        # <hack>
+        # progress(msg + ".", nil) if @progress_msg == msg
+        # </hack>
+        progress(msg, nil) if @progress_msg == msg
+      end
+    end
+
+  end
+end if true # Set to false to disable hack.

data/lib/yard-sketchup.rb

@@ -0,0 +1,29 @@
+require 'yard'
+require 'yard-sketchup/version'
+require 'yard-sketchup/yard/logger'
+require 'yard-sketchup/yard/handlers/class_constants'
+require 'yard-sketchup/yard/handlers/class_enum_constants'
+require 'yard-sketchup/yard/handlers/global_constants'
+
+module SketchUpYARD
+
+  def self.init
+    # https://github.com/burtlo/yard-cucumber/blob/master/lib/yard-cucumber.rb
+    # This registered template works for yardoc
+    # YARD::Templates::Engine.register_template_path File.dirname(__FILE__) + '/templates'
+    # The following static paths and templates are for yard server
+    # YARD::Server.register_static_path File.dirname(__FILE__) + "/templates/default/fulldoc/html"
+
+    YARD::Templates::Engine.register_template_path self.templates_path
+
+    # https://www.rubydoc.info/gems/yard/file/docs/TagsArch.md#Adding_Custom_Tags
+    YARD::Tags::Library.define_tag('Known Bugs', :bug)
+  end
+
+  def self.templates_path
+    File.join(__dir__, 'yard-sketchup', 'templates')
+  end
+
+end
+
+SketchUpYARD.init

data/yard-sketchup.gemspec

@@ -0,0 +1,25 @@
+$LOAD_PATH.unshift File.expand_path('lib', __dir__)
+require 'yard-sketchup/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'yard-sketchup'
+  spec.summary = 'SketchUp Ruby API YARD template.'
+  spec.description = 'SketchUp Ruby API YARD template.'
+  spec.homepage = 'https://github.com/SketchUp/sketchup-yard-template'
+  spec.authors = ['Trimble Inc, SketchUp Team']
+  spec.licenses = ['MIT']
+
+  spec.version = SketchUpYARD::VERSION
+  spec.platform = Gem::Platform::RUBY
+  spec.required_ruby_version = '>= 2.2.0'
+
+  spec.require_paths = ['lib']
+  spec.files = Dir[
+      'lib/**/*',
+      '*.gemspec',
+      'Gemfile'
+  ]
+
+  spec.add_dependency 'yard', '~> 0.9.18'
+  spec.add_development_dependency 'bundler', '~> 1.13'
+end