deg-yard 0.8.7.1

data/lib/yard/cli/i18n.rb

@@ -0,0 +1,69 @@
+require "pathname"
+
+module YARD
+  module CLI
+    # CLI command to support internationalization (a.k.a. i18n).
+    # I18n feature is based on gettext technology.
+    # This command generates .pot file from docstring and extra
+    # documentation.
+    #
+    # @since 0.8.0
+    # @todo Support msgminit and msgmerge features?
+    class I18n < Yardoc
+      def initialize
+        super
+        @options.serializer.basepath = "po/yard.pot"
+      end
+
+      def description
+        'Generates .pot file from source code and extra documentation'
+      end
+
+      def run(*args)
+        if args.size == 0 || !args.first.nil?
+          # fail early if arguments are not valid
+          return unless parse_arguments(*args)
+        end
+
+        YARD.parse(files, excluded)
+
+        serializer = options.serializer
+        pot_file_path = Pathname.new(serializer.basepath).expand_path
+        pot_file_dir_path, pot_file_basename = pot_file_path.split
+        relative_base_path = Pathname.pwd.relative_path_from(pot_file_dir_path)
+        serializer.basepath = pot_file_dir_path.to_s
+        serializer.serialize(pot_file_basename.to_s,
+                             generate_pot(relative_base_path.to_s))
+
+        true
+      end
+
+      private
+
+      def general_options(opts)
+        opts.banner = "Usage: yard i18n [options] [source_files [- extra_files]]"
+        opts.top.list.clear
+        opts.separator "(if a list of source files is omitted, "
+        opts.separator "  {lib,app}/**/*.rb ext/**/*.c is used.)"
+        opts.separator ""
+        opts.separator "Example: yard i18n -o yard.pot - FAQ LICENSE"
+        opts.separator "  The above example outputs .pot file for files in"
+        opts.separator "  lib/**/*.rb to yard.pot including the extra files"
+        opts.separator "  FAQ and LICENSE."
+        opts.separator ""
+        opts.separator "A base set of options can be specified by adding a .yardopts"
+        opts.separator "file to your base path containing all extra options separated"
+        opts.separator "by whitespace."
+        super(opts)
+      end
+
+      def generate_pot(relative_base_path)
+        generator = YARD::I18n::PotGenerator.new(relative_base_path)
+        objects = run_verifier(all_objects)
+        generator.parse_objects(objects)
+        generator.parse_files(options.files || [])
+        generator.generate
+      end
+    end
+  end
+end

data/lib/yard/cli/list.rb

@@ -0,0 +1,22 @@
+module YARD
+  module CLI
+    # Lists all constant and method names in the codebase. Uses {Yardoc} --list.
+    class List < Command
+      def description; 'Lists all constant and methods. Uses `yard doc --list`' end
+
+      # Runs the commandline utility, parsing arguments and displaying a
+      # list of objects
+      #
+      # @param [Array<String>] args the list of arguments.
+      # @return [void]
+      def run(*args)
+        if args.include?('--help')
+          log.puts "Usage: yard list [yardoc_options]"
+          log.puts "Takes the same arguments as yardoc. See yardoc --help"
+        else
+          Yardoc.run('-c', '--list', *args)
+        end
+      end
+    end
+  end
+end

data/lib/yard/cli/markup_types.rb

@@ -0,0 +1,33 @@
+module YARD
+  module CLI
+    # Lists all markup types
+    # @since 0.8.6
+    class MarkupTypes < Command
+      def description; 'Lists all available markup types and libraries' end
+
+      # Runs the commandline utility, parsing arguments and displaying a
+      # list of markup types
+      #
+      # @param [Array<String>] args the list of arguments.
+      # @return [void]
+      def run(*args)
+        log.puts "Available markup types for `doc' command:"
+        log.puts
+        types = Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS
+        exts = Templates::Helpers::MarkupHelper::MARKUP_EXTENSIONS
+        types.sort_by {|name, _| name.to_s }.each do |name, providers|
+          log.puts "[#{name}]"
+          libs = providers.map {|p| p[:lib] }.compact
+          if libs.size > 0
+            log.puts "  Providers: #{libs.join(" ")}"
+          end
+          if exts[name]
+            log.puts "  Extensions: #{exts[name].map {|e| ".#{e}"}.join(" ")}"
+          end
+
+          log.puts
+        end
+      end
+    end
+  end
+end

data/lib/yard/cli/server.rb

@@ -0,0 +1,253 @@
+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
+
+      # @return [Array<String>] a list of scripts to load
+      # @since 0.6.2
+      attr_accessor :scripts
+
+      # @return [Array<String>] a list of template paths to register
+      # @since 0.6.2
+      attr_accessor :template_paths
+
+      # Creates a new instance of the Server command line utility
+      def initialize
+        super
+        self.scripts = []
+        self.template_paths = []
+        self.libraries = {}
+        self.options = SymbolHash.new(false).update(
+          :single_library => true,
+          :caching => false
+        )
+        self.server_options = {:Port => 8808}
+      end
+
+      def description
+        "Runs a local documentation server"
+      end
+
+      def run(*args)
+        optparse(*args)
+
+        select_adapter.setup
+        load_scripts
+        load_template_paths
+        adapter.new(libraries, options, server_options).start
+      end
+
+      private
+
+      def load_scripts
+        scripts.each {|file| load_script(file) }
+      end
+
+      def load_template_paths
+        return if YARD::Config.options[:safe_mode]
+        Templates::Engine.template_paths |= template_paths
+      end
+
+      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, dir = args[index], args[index + 1]
+
+          libver = nil
+          if dir
+            if File.exist?(dir)
+              # Provided dir contains a .yardopts file
+              libver = create_library_version_if_yardopts_exist(library, dir)
+              libver ||= YARD::Server::LibraryVersion.new(library, nil, dir)
+            end
+          else
+            # Check if this dir contains a .yardopts file
+            pwd = Dir.pwd
+            libver = create_library_version_if_yardopts_exist(library, pwd)
+
+            # Check default location
+            yfile = File.join(pwd, '.yardoc')
+            libver ||= YARD::Server::LibraryVersion.new(library, nil, yfile)
+          end
+
+          # Register library
+          if libver
+            libver.yardoc_file = File.expand_path(libver.yardoc_file) if libver.yardoc_file
+            libver.source_path = File.expand_path(libver.source_path) if libver.source_path
+            libraries[library] ||= []
+            libraries[library] |= [libver]
+          else
+            log.warn "Cannot find yardoc db for #{library}: #{dir.inspect}"
+          end
+        end
+      end
+
+      # @param [String] library The library name.
+      # @param [String, nil] dir The argument provided on the CLI after the
+      #   library name. Is supposed to point to either a project directory
+      #   with a Yard options file, or a yardoc db.
+      # @return [LibraryVersion, nil]
+      def create_library_version_if_yardopts_exist(library, dir)
+        if dir
+         options_file = File.join(dir, Yardoc::DEFAULT_YARDOPTS_FILE)
+         if File.exist?(options_file)
+           # Found yardopts, extract db path
+           yfile = extract_db_from_options_file(options_file)
+           db = File.expand_path(yfile, dir)
+
+           # Create libver
+           libver = YARD::Server::LibraryVersion.new(library, nil, db)
+           libver.source_path = dir
+           libver
+         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 add_gems_from_gemfile(gemfile = nil)
+        require 'bundler'
+        gemfile ||= "Gemfile"
+        if File.exist?("#{gemfile}.lock")
+          Bundler::LockfileParser.new(File.read("#{gemfile}.lock")).specs.each do |spec|
+            libraries[spec.name] ||= []
+            libraries[spec.name] |= [YARD::Server::LibraryVersion.new(spec.name, spec.version.to_s, nil, :gem)]
+          end
+        else
+          log.warn "Cannot find #{gemfile}.lock, ignoring --gemfile option"
+        end
+      rescue LoadError
+        log.error "Bundler not available, ignoring --gemfile option"
+      end
+
+      def optparse(*args)
+        opts = OptionParser.new
+        opts.banner = 'Usage: yard server [options] [[library yardoc_file] ...]'
+        opts.separator ''
+        opts.separator 'Example: yard server -m 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('-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.on('-G', '--gemfile [GEMFILE]', 'Serves documentation for gems from Gemfile') do |gemfile|
+          add_gems_from_gemfile(gemfile)
+        end
+        opts.on('-t', '--template-path PATH',
+                'The template path to look for templates in. (used with -t).') do |path|
+          self.template_paths << path
+        end
+        opts.separator ''
+        opts.separator "Web Server Options:"
+        opts.on('-d', '--daemon', 'Daemonizes the server process') do
+          server_options[:daemonize] = true
+        end
+        opts.on('-B HOST', '--bind', 'The host address to bind to') do |host|
+          server_options[:Host] = host.to_s
+        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)
+        opts.on('-e', '--load FILE', 'A Ruby script to load before the source tree is parsed.') do |file|
+          self.scripts << file
+        end
+        parse_options(opts, args)
+
+        if args.empty? && libraries.empty?
+          # No args - try to use current dir
+          add_libraries([File.basename(Dir.pwd), nil])
+
+          # Generate doc for first time
+          libver = libraries.empty? ? nil : libraries.values.first.first
+          if libver and !File.exist?(libver.yardoc_file)
+            generate_doc_for_first_time(libver)
+          end
+        else
+          add_libraries(args)
+          options[:single_library] = false if libraries.size > 1
+        end
+      end
+
+      def generate_doc_for_first_time(libver)
+        log.enter_level(Logger::INFO) do
+          yardoc_file = libver.yardoc_file.sub /^#{Regexp.quote Dir.pwd}[\\\/]+/, ''
+          log.info "No yardoc db found in #{yardoc_file}, parsing source before starting server..."
+        end
+        Dir.chdir(libver.source_path) do
+          Yardoc.run('-n')
+        end
+      end
+
+      def extract_db_from_options_file(options_file)
+        args = File.read_binary(options_file).shell_split
+        db = YARD::Registry.yardoc_file
+        opts = OptionParser.new
+        opts.on('-b', '--db FILE') {|file| db = file }
+
+        begin
+          opts.parse!(args)
+        rescue OptionParser::ParseError
+          args.shift if args.first && args.first[0,1] != '-'
+          retry
+        end
+
+        db
+      end
+    end
+  end
+end

data/lib/yard/cli/stats.rb

@@ -0,0 +1,213 @@
+module YARD
+  module CLI
+    # @since 0.6.0
+    class Stats < Yardoc
+      include Templates::Helpers::BaseHelper
+
+      # Maintains the order in which +stats_for_+ statistics methods should be
+      # printed.
+      #
+      # @see #print_statistics
+      STATS_ORDER = [:files, :modules, :classes, :constants, :methods]
+
+      # @return [Boolean] whether to parse and load registry
+      attr_accessor :parse
+
+      # @param [Boolean] parse whether to parse and load registry (see {#parse})
+      def initialize(parse = true)
+        super()
+        @parse = parse
+        @undoc_list = nil
+        @compact = false
+      end
+
+      def description
+        "Prints documentation statistics on a set of files"
+      end
+
+      # Runs the commandline utility, parsing arguments and generating
+      # output if set.
+      #
+      # @param [Array<String>] args the list of arguments
+      # @return [void]
+      def run(*args)
+        parse_arguments(*args)
+
+        if use_cache
+          Registry.load!
+        elsif parse
+          YARD.parse(files, excluded)
+          Registry.save(use_cache) if save_yardoc
+        end
+
+        print_statistics
+        print_undocumented_objects
+      end
+
+      # Prints statistics for different object types
+      #
+      # To add statistics for a specific type, add a method +#stats_for_TYPE+
+      # to this class that calls {#output}.
+      def print_statistics
+        @total, @undocumented = 0, 0
+        meths = methods.map {|m| m.to_s }.grep(/^stats_for_/)
+        STATS_ORDER.each do |meth|
+          mname = "stats_for_#{meth}"
+          if meths.include?(mname)
+            send(mname)
+            meths.delete(mname)
+          end
+        end
+        meths.each {|m| send(m) }
+        if @total == 0
+          total = 0
+        else
+          total = (@total - @undocumented).to_f / @total.to_f * 100
+        end
+        log.puts("% 3.2f%% documented" % total)
+      end
+
+      # Prints list of undocumented objects
+      def print_undocumented_objects
+        return if !@undoc_list || @undoc_list.empty?
+        log.puts
+        log.puts "Undocumented Objects:"
+
+        objects = @undoc_list.sort_by {|o| o.file }
+        max = objects.sort_by {|o| o.path.length }.last.path.length
+        if @compact
+          objects.each do |object|
+            log.puts("%-#{max}s     (%s)" % [object.path,
+              [object.file, object.line].compact.join(":")])
+          end
+        else
+          last_file = nil
+          objects.each do |object|
+            if object.file != last_file
+              log.puts
+              log.puts "(in file: #{object.file})"
+            end
+            log.puts object.path
+            last_file = object.file
+          end
+        end
+      end
+
+      # @return [Array<CodeObjects::Base>] all the parsed objects in the registry,
+      #   removing any objects that are not visible (private, protected) depending
+      #   on the arguments passed to the command.
+      def all_objects
+        @all_objects ||= run_verifier Registry.all
+      end
+
+      # Statistics for files
+      def stats_for_files
+        files = []
+        all_objects.each {|o| files |= [o.file] }
+        output "Files", files.size
+      end
+
+      # Statistics for modules
+      def stats_for_modules
+        output "Modules", *type_statistics(:module)
+      end
+
+      # Statistics for classes
+      def stats_for_classes
+        output "Classes", *type_statistics(:class)
+      end
+
+      # Statistics for constants
+      def stats_for_constants
+        output "Constants", *type_statistics(:constant)
+      end
+
+      # Statistics for methods
+      def stats_for_methods
+        objs = all_objects.select {|m| m.type == :method }
+        objs.reject! {|m| m.is_alias? || !m.is_explicit? }
+        undoc = objs.select {|m| m.docstring.blank? && !m.overridden_method }
+        @undoc_list |= undoc if @undoc_list
+        output "Methods", objs.size, undoc.size
+      end
+
+      # Prints a statistic to standard out. This method is optimized for
+      # getting Integer values, though it allows any data to be printed.
+      #
+      # @param [String] name the statistic name
+      # @param [Integer, String] data the numeric (or any) data representing
+      #   the statistic. If +data+ is an Integer, it should represent the
+      #   total objects of a type.
+      # @param [Integer, nil] undoc number of undocumented objects for the type
+      # @return [void]
+      def output(name, data, undoc = nil)
+        @total += data if data.is_a?(Integer) && undoc
+        @undocumented += undoc if undoc.is_a?(Integer)
+        if undoc
+          data = ("%5s (% 5d undocumented)" % [data, undoc])
+        else
+          data = "%5s" % data
+        end
+        log.puts("%-12s %s" % [name + ":", data])
+      end
+
+      private
+
+      def type_statistics(type)
+        objs = all_objects.select {|m| m.type == type }
+        undoc = objs.find_all {|m| m.docstring.blank? }
+        @undoc_list |= undoc if @undoc_list
+        [objs.size, undoc.size]
+      end
+
+      # Parses commandline options.
+      # @param [Array<String>] args each tokenized argument
+      def optparse(*args)
+        opts = OptionParser.new
+        opts.banner = "Usage: yard stats [options] [source_files]"
+
+        opts.separator "(if a list of source files is omitted, lib/**/*.rb ext/**/*.c is used.)"
+
+        general_options(opts)
+        output_options(opts)
+        tag_options(opts)
+        common_options(opts)
+        parse_options(opts, args)
+        parse_files(*args) unless args.empty?
+      end
+
+      def general_options(opts)
+        super(opts)
+
+        opts.on('--list-undoc', 'List all undocumented objects') do
+          @undoc_list = []
+        end
+
+        opts.on('--compact', 'Compact undocumented objects listing') do
+          @compact = true
+        end
+
+        opts.on('--no-public', "Don't include public methods in statistics.") do
+          visibilities.delete(:public)
+        end
+
+        opts.on('--protected', "Include protected methods in statistics.") do
+          visibilities.push(:protected)
+        end
+
+        opts.on('--private', "Include private methods in statistics.") do
+          visibilities.push(:private)
+        end
+
+        opts.on('--no-private', "Don't include objects with @private tag in statistics.") do
+          options[:verifier].add_expressions '!object.tag(:private) &&
+            (object.namespace.type == :proxy || !object.namespace.tag(:private))'
+        end
+
+        opts.on('--query QUERY', "Only includes objects that match a specific query") do |query|
+          options[:verifier].add_expressions(query.taint)
+        end
+      end
+    end
+  end
+end