yard 0.5.8 → 0.6.0

data/lib/yard/cli/diff.rb

@@ -0,0 +1,176 @@
+require 'tmpdir'
+require 'fileutils'
+require 'open-uri'
+
+module YARD
+  module CLI
+    # CLI command to return the objects that were added/removed from 2 versions
+    # of a project (library, gem, working copy).
+    # @since 0.6.0
+    class Diff < Command
+      def initialize
+        require_rubygems
+        super
+        @list_all = false
+        log.show_backtraces = true
+      end
+      
+      def description
+        'Returns the object diff of two gems or .yardoc files'
+      end
+      
+      def run(*args)
+        registry = optparse(*args).map do |gemfile|
+          if load_gem_data(gemfile)
+            log.info "Found #{gemfile}"
+            Registry.all.map {|o| o.path }
+          else
+            log.error "Cannot find gem #{gemfile}"
+            nil
+          end
+        end.compact
+        
+        return if registry.size != 2
+
+        [   ["Added objects", registry[1] - registry[0]],
+            ["Removed objects", registry[0] - registry[1]]].each do |name, objects|
+          next if objects.empty?
+          last_object = nil
+          all_objects_notice = false
+          puts name + ":"
+          objects.sort.each do |object|
+            if !@list_all && last_object && object =~ /#{Regexp.quote last_object}(::|\.|#)/
+              print " (...)" unless all_objects_notice
+              all_objects_notice = true
+              next
+            else
+              puts
+            end
+            all_objects_notice = false
+            print "  " + object
+            last_object = object
+          end
+          puts
+          puts
+        end
+      end
+      
+      private
+      
+      def load_gem_data(gemfile)
+        Registry.clear
+        
+        # First check for argument as .yardoc file
+        [File.join(gemfile, '.yardoc'), gemfile].each do |yardoc|
+          log.info "Searching for .yardoc db at #{yardoc}"
+          if File.directory?(yardoc)
+            Registry.load_yardoc(yardoc)
+            Registry.load_all
+            return true
+          end
+        end
+        
+        # Next check installed RubyGems
+        gemfile_without_ext = gemfile.sub(/\.gem$/, '')
+        log.info "Searching for installed gem #{gemfile_without_ext}"
+        Gem.source_index.find_name('').find do |spec| 
+          if spec.full_name == gemfile_without_ext
+            if yardoc = Registry.yardoc_file_for_gem(spec.name, "= #{spec.version}")
+              Registry.load_yardoc(yardoc)
+              Registry.load_all
+            else
+              log.enter_level(Logger::ERROR) do
+                olddir = Dir.pwd
+                Gems.run(spec.name, spec.version.to_s)
+                Dir.chdir(olddir)
+              end
+            end
+            return true
+          end
+        end
+        
+        # Look for local .gem file
+        gemfile += '.gem' unless gemfile =~ /\.gem$/
+        log.info "Searching for local gem file #{gemfile}"
+        if File.exist?(gemfile)
+          File.open(gemfile, 'rb') do |io|
+            expand_and_parse(gemfile, io)
+          end
+          return true
+        end
+        
+        # Remote gemfile from rubygems.org
+        url = "http://rubygems.org/downloads/#{gemfile}"
+        log.info "Searching for remote gem file #{url}"
+        begin
+          open(url) {|io| expand_and_parse(gemfile, io) }
+          return true
+        rescue OpenURI::HTTPError
+        end
+        false
+      end
+      
+      def expand_and_parse(gemfile, io)
+        dir = expand_gem(gemfile, io)
+        generate_yardoc(dir)
+        cleanup(gemfile)
+      end
+      
+      def generate_yardoc(dir)
+        olddir = Dir.pwd
+        Dir.chdir(dir)
+        log.enter_level(Logger::ERROR) { Yardoc.run('-n', '--no-save') }
+        Dir.chdir(olddir)
+      end
+      
+      def expand_gem(gemfile, io)
+        tmpdir = File.join(Dir.tmpdir, gemfile)
+        log.info "Expanding #{gemfile} to #{tmpdir}..."
+        FileUtils.mkdir_p(tmpdir)
+        Gem::Package.open(io) do |pkg|
+          pkg.each do |entry|
+            pkg.extract_entry(tmpdir, entry)
+          end
+        end
+        tmpdir
+      end
+
+      def require_rubygems
+        require 'rubygems'
+        require 'rubygems/package'
+      rescue LoadError => e
+        log.error "Missing RubyGems, cannot run this command."
+        raise(e)
+      end
+      
+      def cleanup(gemfile)
+        dir = File.join(Dir.tmpdir, gemfile)
+        log.info "Cleaning up #{dir}..."
+        FileUtils.rm_rf(dir)
+      end
+      
+      def optparse(*args)
+        opts = OptionParser.new
+        opts.banner = "Usage: yard diff [options] oldgem newgem"
+        opts.separator ""
+        opts.separator "Example: yard diff yard-0.5.6 yard-0.5.8"
+        opts.separator ""
+        opts.separator "If the files don't exist locally, they will be grabbed using the `gem fetch`"
+        opts.separator "command. If the gem is a .yardoc directory, it will be used. Finally, if the"
+        opts.separator "gem name matches an installed gem (full name-version syntax), that gem will be used."
+        
+        opts.on('-a', '--all', 'List all objects, even if they are inside added/removed module/class') do
+          @list_all = true
+        end
+        common_options(opts)
+        parse_options(opts, args)
+        unless args.size == 2
+          puts opts.banner
+          exit(0)
+        end
+          
+        args
+      end
+    end
+  end
+end

data/lib/yard/cli/gems.rb

@@ -0,0 +1,74 @@
+module YARD
+  module CLI
+    # @since 0.6.0
+    class Gems < Command
+      def initialize
+        @rebuild = false
+        @gems = []
+      end
+      
+      def description; "Builds YARD index for gems" end
+      
+      # Runs the commandline utility, parsing arguments and generating
+      # YARD indexes for gems.
+      # 
+      # @param [Array<String>] args the list of arguments
+      # @return [void] 
+      def run(*args)
+        optparse(*args)
+        @gems += Gem.source_index.find_name('') if @gems.empty?
+        build_gems
+      end
+      
+      private
+      
+      # Builds .yardoc files for all non-existing gems
+      # @param [Array] gems
+      def build_gems
+        require 'rubygems'
+        @gems.each do |spec|
+          ver = "= #{spec.version}"
+          dir = Registry.yardoc_file_for_gem(spec.name, ver)
+          if dir && File.directory?(dir) && !@rebuild
+            log.debug "#{spec.name} index already exists at '#{dir}'"
+          else
+            yfile = Registry.yardoc_file_for_gem(spec.name, ver, true)
+            next unless yfile
+            next unless File.directory?(spec.full_gem_path)
+            Registry.clear
+            Dir.chdir(spec.full_gem_path)
+            log.info "Building yardoc index for gem: #{spec.full_name}"
+            Yardoc.run('--no-stats', '-n', '-b', yfile)
+          end
+        end
+      end
+      
+      def add_gems(gems)
+        gems.each_slice(2) do |gem, ver_require|
+          specs = Gem.source_index.find_name(gem, ver_require || ">= 0")
+          @gems += specs unless specs.empty?
+        end
+      end
+      
+      # Parses options
+      def optparse(*args)
+        opts = OptionParser.new
+        opts.banner = 'Usage: yard gems [options] [gem_name [version]]'
+        opts.separator ""
+        opts.separator "#{description}. If no gem_name is given,"
+        opts.separator "all gems are built."
+        opts.separator ""
+        opts.on('--rebuild', 'Rebuilds index') do
+          @rebuild = true
+        end
+        opts.on('--legacy', 'Use old style parser and handlers. Unavailable under Ruby 1.8.x') do
+          YARD::Parser::SourceParser.parser_type = :ruby18
+        end
+        
+        common_options(opts)
+        parse_options(opts, args)
+        add_gems(args)
+      end
+    end
+  end
+end

data/lib/yard/cli/{yard_graph.rb → graph.rb}

@@ -3,8 +3,9 @@ module YARD
     # A command-line utility to generate Graphviz graphs from
     # a set of objects
     # 
-    # @see YardGraph#run
-    class YardGraph < Base
+    # @see Graph#run
+    # @since 0.6.0
+    class Graph < Command
       # The options parsed out of the commandline.
       # Default options are:
       #   :format => :dot
@@ -13,10 +14,6 @@ module YARD
       # The set of objects to include in the graph.
       attr_reader :objects
 
-      # Helper method to run the utility on an instance.
-      # @see #run
-      def self.run(*args) new.run(*args) end
-        
       # Creates a new instance of the command-line utility
       def initialize
         super
@@ -24,10 +21,14 @@ module YARD
         @options = SymbolHash[:format => :dot]
       end
       
+      def description
+        "Graphs class diagram using Graphviz"
+      end
+    
       # Runs the command-line utility.
       # 
       # @example
-      #   grapher = YardGraph.new
+      #   grapher = Graph.new
       #   grapher.run('--private')
       # @param [Array<String>] args each tokenized argument
       def run(*args)
@@ -90,7 +91,7 @@ module YARD
         common_options(opts)
         parse_options(opts, args)
 
-        @verifier = Verfier.new("object.type != :method || #{visibilities.uniq.inspect}.include?(object.visibility)")
+        @verifier = Verifier.new("object.type != :method || #{visibilities.uniq.inspect}.include?(object.visibility)")
         if args.first
           @objects = args.map {|o| Registry.at(o) }.compact
         else

data/lib/yard/cli/help.rb

@@ -0,0 +1,18 @@
+module YARD
+  module CLI
+    # Handles help for commands
+    # @since 0.6.0
+    class Help < Command
+      def description; "Retrieves help for a command" end
+      
+      def run(*args)
+        if args.first && cmd = CommandParser.commands[args.first.to_sym]
+          cmd.run('--help')
+        else
+          puts "Command #{args.first} not found." if args.first
+          CommandParser.run('--help')
+        end
+      end
+    end
+  end
+end

data/lib/yard/cli/server.rb

@@ -0,0 +1,137 @@
+module YARD
+  module CLI
+    # A local documentation server
+    # @since 0.6.0
+    class Server < Command
+      # @return [Hash] a list of options to pass to the doc server
+      attr_accessor :options
+      
+      # @return [Hash] a list of options to pass to the web server
+      attr_accessor :server_options
+      
+      # @return [Hash] a list of library names and yardoc files to serve
+      attr_accessor :libraries
+      
+      # @return [Adapter] the adapter to use for loading the web server
+      attr_accessor :adapter
+      
+      def description
+        "Runs a local documentation server"
+      end
+      
+      def run(*args)
+        self.libraries = {}
+        self.options = SymbolHash.new(false).update(
+          :single_library => true,
+          :caching => false
+        )
+        self.server_options = {:Port => 8808}
+        optparse(*args)
+        
+        select_adapter
+        adapter.new(libraries, options, server_options).start
+      end
+      
+      private
+      
+      def select_adapter
+        return adapter if adapter
+        require 'rubygems'
+        require 'rack'
+        self.adapter = YARD::Server::RackAdapter
+      rescue LoadError
+        self.adapter = YARD::Server::WebrickAdapter
+      end
+      
+      def add_libraries(args)
+        (0...args.size).step(2) do |index|
+          library, yardoc = args[index], args[index + 1]
+          yardoc ||= '.yardoc'
+          if File.exist?(yardoc)
+            libraries[library] ||= []
+            libraries[library] << YARD::Server::LibraryVersion.new(library, nil, yardoc)
+          else
+            log.warn "Cannot find yardoc db for #{library}: #{yardoc}"
+          end
+        end
+      end
+      
+      def add_gems
+        require 'rubygems'
+        Gem.source_index.find_name('').each do |spec|
+          libraries[spec.name] ||= []
+          libraries[spec.name] << YARD::Server::LibraryVersion.new(spec.name, spec.version.to_s, nil, :gem)
+        end
+      end
+      
+      def optparse(*args)
+        opts = OptionParser.new
+        opts.banner = 'Usage: yard server [options] [[library yardoc_file] ...]'
+        opts.separator ''
+        opts.separator 'Example: yard server yard .yardoc ruby-core ../ruby/.yardoc'
+        opts.separator 'The above example serves documentation for YARD and Ruby-core'
+        opts.separator ''
+        opts.separator 'If no library/yardoc_file is specified, the server uses'
+        opts.separator 'the name of the current directory and `.yardoc` respectively'
+        opts.separator ''
+        opts.separator "General Options:"
+        opts.on('-e', '--load FILE', 'A Ruby script to load before the source tree is parsed.') do |file|
+          if !require(file.gsub(/\.rb$/, ''))
+            log.error "The file `#{file}' was already loaded, perhaps you need to specify the absolute path to avoid name collisions."
+            exit
+          end
+        end
+        opts.on('-m', '--multi-library', 'Serves documentation for multiple libraries') do
+          options[:single_library] = false
+        end
+        opts.on('-c', '--cache', 'Caches all documentation to document root (see --docroot)') do
+          options[:caching] = true
+        end
+        opts.on('-r', '--reload', 'Reparses the library code on each request') do
+          options[:incremental] = true
+        end
+        opts.on('-g', '--gems', 'Serves documentation for installed gems') do
+          add_gems
+        end
+        opts.separator ''
+        opts.separator "Web Server Options:"
+        opts.on('-d', '--daemon', 'Daemonizes the server process') do
+          server_options[:daemonize] = true
+        end
+        opts.on('-p PORT', '--port', 'Serves documentation on PORT') do |port|
+          server_options[:Port] = port.to_i
+        end
+        opts.on('--docroot DOCROOT', 'Uses DOCROOT as document root') do |docroot|
+          server_options[:DocumentRoot] = File.expand_path(docroot)
+        end
+        opts.on('-a', '--adapter ADAPTER', 'Use the ADAPTER (full Ruby class) for web server') do |adapter|
+          if adapter.downcase == 'webrick'
+            self.adapter = YARD::Server::WebrickAdapter
+          elsif adapter.downcase == 'rack'
+            self.adapter = YARD::Server::RackAdapter
+          else
+            self.adapter = eval(adapter)
+          end
+        end
+        opts.on('-s', '--server TYPE', 'Use a specific server type eg. thin,mongrel,cgi (Rack specific)') do |type|
+          server_options[:server] = type
+        end
+        common_options(opts)
+        parse_options(opts, args)
+        
+        if args.empty? && libraries.empty?
+          if !File.exist?('.yardoc')
+            log.enter_level(Logger::INFO) do
+              log.info "No .yardoc file found in current directory, parsing source before starting server..."
+            end
+            Yardoc.run('-n')
+          end
+          add_libraries([File.basename(Dir.pwd), '.yardoc'])
+        else
+          add_libraries(args)
+          options[:single_library] = false if libraries.size > 1
+        end
+      end
+    end
+  end
+end