doc 0.0.0.0 → 0.0.1

data/lib/doc/config_error.rb

@@ -0,0 +1,11 @@
+module Doc
+  class ConfigError < Exception
+    def initialize(object, message)
+      super("#{object.class.name}: #{message}").tap do |e|
+        if Exception === message
+          e.set_backtrace(message.backtrace)
+        end
+      end
+    end
+  end
+end

data/lib/doc/config_object.rb

@@ -0,0 +1,80 @@
+module Doc
+  class ConfigObject
+    def initialize(default_key, *arguments, &block)
+      @hash = {}
+      arguments = arguments.dup
+      if arguments.last.is_a?(Hash)
+        @hash.merge!(arguments.pop)
+      end
+      unless arguments.empty?
+        @hash[default_key] = arguments
+      end
+
+      block.call(self) if block
+    end
+
+    def [](key)
+      @hash[key]
+    end
+
+    def []=(key, value)
+      @hash[key] = value
+    end
+
+    def keys
+      @hash.keys
+    end
+
+    def method_missing(method, *arguments)
+      case method.to_s
+      when /\!$/
+        check_argument_count arguments, 0
+        @hash[$`.to_sym] = true
+      when /\?$/
+        check_argument_count arguments, 0
+        @hash[$`.to_sym] && true
+      else
+        if arguments.empty?
+          @hash[method]
+        else
+          check_argument_count arguments, 1
+          @hash[method] = arguments.first
+        end
+      end
+    end
+
+    def check_options!(required_keys, optional_keys)
+      errors = []
+
+      unless (missing_keys = required_keys - keys).empty?
+        errors << "missing required keys: #{missing_keys.join(', ')}"
+      end
+
+      left_keys = keys - required_keys
+      optional_keys.each do |key_group|
+        key_group = Array(key_group)
+        if key_group.length > 1
+          if (clashing_keys = keys & key_group).length > 1
+            errors << "clash of mutually exclusive keys: #{clashing_keys.join(', ')}"
+          end
+        end
+        left_keys -= key_group
+      end
+      unless left_keys.empty?
+        errors << "unknown keys: #{left_keys.join(', ')}"
+      end
+
+      unless errors.empty?
+        raise ConfigError.new(self, errors.join('; '))
+      end
+    end
+
+  private
+
+    def check_argument_count(arguments, accepts)
+      if arguments.length != accepts
+        raise ArgumentError.new("wrong number of arguments (#{arguments.length} for #{accepts})")
+      end
+    end
+  end
+end

data/lib/doc/configurator.rb

@@ -0,0 +1,38 @@
+module Doc
+  class Configurator
+    class << self
+      def inherited(subclass)
+        RootConfig.configurator subclass.name.underscore.split('/').last, subclass
+      end
+
+      def default_config_key(value = nil)
+        @default_config_key = value.to_sym if value
+        @default_config_key || :default
+      end
+    end
+
+    attr_reader :documentor, :config
+    def initialize(documentor, *arguments, &block)
+      @documentor = documentor
+      @config = ConfigObject.new(self.class.default_config_key, *arguments, &block)
+    end
+
+    abstract_method :configure, :tasks
+
+  private
+
+    PARSABLE_EXTENSIONS_GLOB = "{#{%w[rb  c m C M cc CC mm MM c++ cxx cpp  h H hh HH hm h++ hpp hxx  y].join(',')}}"
+
+    def sources_dir
+      documentor.sources_dir.tap(&:mkpath)
+    end
+
+    def builder(options)
+      Builder.new(documentor, options)
+    end
+
+    def merger(options)
+      Merger.new(documentor, options)
+    end
+  end
+end

data/lib/doc/configurator/gems.rb

@@ -0,0 +1,70 @@
+module Doc
+  class Configurator
+    class Gems < Configurator
+      default_config_key :only
+
+      def configure(update)
+        config.check_options!([], [[:only, :except], :versions, :prerelease])
+
+        [:only, :except].each do |key|
+          config[key] = Array(config[key]).map(&:to_s) if config[key]
+        end
+
+        @prerelease = !!config[:prerelease]
+        @specs = config[:versions] && config[:versions].to_sym == :all ? all_specs(@prerelease) : latest_specs(@prerelease)
+
+        if config[:only]
+          absent = config[:only] - @specs.map(&:name)
+          unless absent.empty?
+            raise ConfigError.new(self, "can't find gems: #{absent.join(', ')}")
+          end
+        end
+
+        if config[:only]
+          @specs = @specs.select{ |spec| config[:only].include?(spec.name) }
+        elsif config[:except]
+          @specs = @specs.reject{ |spec| config[:except].include?(spec.name) }
+        end
+        @specs = @specs.sort_by{ |spec| [spec.name.downcase, spec.sort_obj] }
+      end
+
+      def tasks
+        @specs.map do |spec|
+          main = spec.rdoc_options.each_cons(2).select{ |key, value| %w[--main -m].include?(key) }.map(&:last).first
+          Dir.chdir(spec.full_gem_path) do
+            file_list = FileList.new
+            file_list.include *spec.extra_rdoc_files
+            file_list.include *spec.require_paths
+
+            builder({
+              :title => "gem #{spec.full_name}",
+              :source_dir => spec.full_gem_path,
+              :dir_name => "gem.#{spec.full_name}",
+              :paths => file_list,
+              :main => main,
+            })
+          end
+        end
+      end
+
+    private
+
+      def latest_specs(prerelease)
+        Gem::Specification.latest_specs(prerelease)
+      end
+
+      def all_specs(prerelease)
+        if prerelease
+          Gem::Specification.to_a
+        else
+          Gem::Specification.select{ |spec| !spec.version.prerelease? }
+        end
+      end
+
+      def sort_specs(specs)
+        specs.sort_by{ |spec| [spec.name.downcase, spec.name, spec.version] }
+      end
+    end
+    RootConfig.send(:alias_method, :gem, :gems)
+  end
+end

data/lib/doc/configurator/paths.rb

@@ -0,0 +1,90 @@
+require 'digest'
+
+module Doc
+  class Configurator
+    class Paths < Configurator
+      default_config_key :glob
+
+      def configure(update)
+        config.check_options!([], [:glob, :main, :file_list, :title])
+
+        @path_pairs = []
+        Array(config[:glob]).map do |glob|
+          if glob[0, 1] == '~' && (parts = glob.split(File::SEPARATOR, 2)).length == 2
+            FSPath(glob).expand_path.glob.map do |path|
+              unexpanded_part = FSPath(parts[0])
+              @path_pairs << [path, unexpanded_part / path.relative_path_from(unexpanded_part.expand_path)]
+            end
+          else
+            @path_pairs.concat(FSPath(glob).glob)
+          end
+        end.flatten
+
+        if @path_pairs.empty?
+          raise ConfigError.new(self, "expanding #{config[:glob].join(', ')} gave empty list")
+        end
+
+        @main = Array(config[:main])
+
+        if config[:file_list]
+          @file_list = config[:file_list]
+          case @file_list
+          when Proc
+            if @file_list.arity != 1
+              raise ConfigError.new(self, "proc should have on parameter for instance of FileList")
+            end
+          when Array
+            unless @file_list.all?{ |rule| rule =~ /^\+|-/ }
+              raise ConfigError.new(self, "all rules must start with + or -")
+            end
+          else
+            raise ConfigError.new(self, "file_list should be either array in form %w[+a/* -b/*] or proc receiving instance of FileList")
+          end
+        end
+
+        if @title = config[:title]
+          unless @title.is_a?(Proc) && @title.arity == 1
+            raise ConfigError.new(self, "title should be an instance of Proc receiving one argument (path)")
+          end
+        end
+      end
+
+      def tasks
+        @path_pairs.map do |pair|
+          path, unexpanded_path = pair
+          unexpanded_path ||= path
+          Dir.chdir(path) do
+            paths = nil
+            if @file_list
+              file_list = FileList.new
+              case @file_list
+              when Proc
+                @file_list.call(file_list)
+              when Array
+                @file_list.each do |rule|
+                  file_list.send(rule[0, 1] == '+' ? :include : :exclude, rule[1..-1])
+                end
+              end
+            end
+
+            main = nil
+            if @main
+              @main.each do |main|
+                break if main = Dir[main].first
+              end
+            end
+
+            builder({
+              :title => @title ? @title[unexpanded_path].to_s : "path #{unexpanded_path}",
+              :source_dir => path,
+              :dir_name => "path.#{unexpanded_path.to_s.gsub('_', '').gsub('/', '_').gsub(/[^a-z0-9\-_]/i, '-')}.#{Digest::SHA1.hexdigest(path.to_s)}",
+              :paths => file_list,
+              :main => main,
+            })
+          end
+        end
+      end
+    end
+    RootConfig.send(:alias_method, :path, :paths)
+  end
+end

data/lib/doc/configurator/rails.rb

@@ -0,0 +1,98 @@
+require 'shellwords'
+
+module Doc
+  class Configurator
+    class Rails < Configurator
+      default_config_key :version
+
+      def configure(update)
+        config.check_options!([], [:version, :prerelease])
+
+        search_versions = Array(config[:version] || [nil])
+        @versions = search_versions.map do |search_version|
+          requirement = Gem::Requirement.new(search_version.is_a?(Integer) ? "~> #{search_version}" : search_version)
+          versions = Gem::Specification.find_all_by_name('rails', requirement).map(&:version)
+          versions.reject!(&:prerelease?) unless config[:prerelease]
+          unless version = versions.sort.last
+            raise ConfigError.new(self, "can't find rails version matching: #{search_version}")
+          end
+          version
+        end
+      end
+
+      def tasks
+        @versions.map do |version|
+          builder({
+            :title => "rails-#{version}",
+            :dir_name => "rails-#{version}",
+            :paths => paths_to_document_for_version(version),
+          })
+        end
+      end
+
+    private
+
+      def version_less_than_3?(version)
+        version.segments.first < 3
+      end
+
+      def paths_to_document_for_version(version)
+        code = if version_less_than_3?(version)
+          <<-RUBY
+            require 'rake/rdoctask'
+            gem 'rails', ARGV.first
+
+            Rake::FileList.class_eval do
+              alias_method :original_include, :include
+              def include(*paths, &block)
+                original_include(*fix_paths(*paths), &block)
+              end
+
+              alias_method :original_exclude, :exclude
+              def exclude(*paths, &block)
+                original_exclude(*fix_paths(*paths), &block)
+              end
+
+              def fix_paths(*paths)
+                paths.map do |path|
+                  if path.is_a?(String)
+                    path.sub(%r{^vendor\/rails\/([^\/]+)(?=\/)}) do
+                      name = {'railties' => 'rails'}[$1] || $1
+                      Gem.loaded_specs[name].full_gem_path
+                    end
+                  else
+                    path
+                  end
+                end
+              end
+            end
+
+            Rake::RDocTask.class_eval do
+              def define
+                puts rdoc_files if name == 'rails'
+              end
+            end
+
+            load 'tasks/documentation.rake'
+          RUBY
+        else
+          <<-RUBY
+            require 'rake/rdoctask'
+            gem 'rails', ARGV.first
+
+            class RDocTaskWithoutDescriptions < Rake::RDocTask
+              def initialize(name = :rdoc)
+                super
+                puts rdoc_files if name == 'rails'
+              end
+            end
+
+            load 'rails/tasks/documentation.rake'
+          RUBY
+        end
+        args = %W[ruby -r rubygems -e #{code} -- #{version}]
+        IO.popen(args.shelljoin, &:readlines).map(&:strip)
+      end
+    end
+  end
+end

data/lib/doc/configurator/ruby.rb

@@ -0,0 +1,167 @@
+module Doc
+  class Configurator
+    class Ruby < Doc::Configurator
+      smart_autoload :PathInfo, :VersionSpecifier, :Source, :Stdlib
+      include Source, Stdlib
+
+      default_config_key :binary
+
+      def configure(update)
+        config.check_options!([], [[:source, :archive, :version, :binary], :format, :except, :index])
+
+        @source_dirs = case
+        when config[:source]
+          Array(config[:source]).map{ |source| from_dir(source) }
+        when config[:archive]
+          Array(config[:archive]).map{ |archive| from_archive(archive) }
+        when config[:version]
+          Array(config[:version]).map{ |version| by_version(version, update) }
+        else
+          Array(config[:binary] || [nil]).map{ |binary| by_binary(binary, update) }
+        end
+
+        @format = (config[:format] || :all).to_sym
+        unless avaliable_formats.include?(@format)
+          raise "format can be one of: #{avaliable_formats.join(', ')}"
+        end
+        if [:separate, :integrate].include?(@format)
+          @stdlib_config = stdlib_config(update) or raise 'can\'t get stdlib config'
+        end
+
+        @except_regexp = /^(?:lib|ext)\/(?:#{Array(config[:except]).map(&Regexp.method(:escape)).join('|')})(?:.rb$|\/)/
+
+        if config[:index]
+          @index = FSPath(config[:index])
+          unless @index.directory? && (@index / 'index.html').file?
+            raise 'index should be a path to directory with index.html inside'
+          end
+        end
+      rescue => e
+        raise ConfigError.new(self, e)
+      end
+
+      def avaliable_formats
+        @avaliable_formats ||= methods.map{ |m| m[/^tasks_(.*)$/, 1] }.compact.map(&:to_sym)
+      end
+
+      def tasks
+        @source_dirs.map do |source_dir|
+          source_dir.touch
+          Dir.chdir(source_dir) do
+            send("tasks_#@format", source_dir)
+          end
+        end
+      end
+
+      def tasks_all(source_dir)
+        file_list = FileList.new
+        file_list.include(*%w[NEWS LEGAL COPYING GPL LGPL])
+        file_list.include("*.#{PARSABLE_EXTENSIONS_GLOB}")
+        file_list.include("{lib,ext}/**/*.#{PARSABLE_EXTENSIONS_GLOB}")
+        file_list.exclude @except_regexp
+
+        builder({
+          :title => source_dir.basename.to_s,
+          :source_dir => source_dir,
+          :dir_name => source_dir.basename.to_s,
+          :paths => file_list,
+          :index => @index,
+        })
+      end
+
+      def tasks_separate(source_dir)
+        tasks = []
+
+        core_paths_a = core_paths.to_a
+
+        file_list = FileList.new
+        file_list.add(*core_paths_a)
+        file_list.exclude @except_regexp
+
+        tasks << builder({
+          :title => "#{source_dir.basename} core",
+          :source_dir => source_dir,
+          :dir_name => "#{source_dir.basename}_core",
+          :paths => file_list,
+          :index => @index,
+        })
+
+        stdlib_tasks = []
+        @stdlib_config['targets'].each do |target|
+          name = target['target']
+          file_list = FileList.new
+          file_list.add(*stdlib_paths_for_target(name) - core_paths_a)
+          file_list.exclude @except_regexp
+
+          unless file_list.empty?
+            stdlib_tasks << builder({
+              :title => name,
+              :source_dir => source_dir,
+              :dir_name => "#{source_dir.basename}_#{name.gsub(/[^a-z0-9\-_]/i, '-')}",
+              :paths => file_list,
+              :main => target['mainpage'],
+              :no_auto_add_paths => true,
+            })
+          end
+        end
+
+        tasks << merger({
+          :title => "#{source_dir.basename} stdlib",
+          :dir_name => "#{source_dir.basename}_stdlib",
+          :tasks => stdlib_tasks
+        })
+
+        tasks
+      end
+
+      def tasks_integrate(source_dir)
+        file_list = FileList.new
+        file_list.add(core_paths)
+        @stdlib_config['targets'].each do |target|
+          file_list.add(stdlib_paths_for_target(target['target']))
+        end
+        file_list.exclude @except_regexp
+        builder({
+          :title => "#{source_dir.basename} +stdlib",
+          :source_dir => source_dir,
+          :dir_name => "#{source_dir.basename}_with_stdlib",
+          :paths => file_list,
+          :index => @index,
+        })
+      end
+
+    private
+
+      def core_paths(dir = nil)
+        file_list = []
+
+        dot_document_path = FSPath('.document')
+        dot_document_path = dir / dot_document_path if dir
+
+        if dot_document_path.exist?
+          dot_document_path.readlines.map(&:strip).reject{ |line| line.empty? || line[0] == ?# }
+        else
+          ['*']
+        end.each do |glob|
+          FSPath.glob(dir ? dir / glob : glob) do |path|
+            if path.directory?
+              file_list.concat(core_paths(path))
+            else
+              file_list << path.to_s
+            end
+          end
+        end
+
+        file_list
+      end
+
+      def stdlib_paths_for_target(name)
+        file_list = FileList.new
+        file_list.include("{lib,ext}/#{name}{,/**/*}.#{PARSABLE_EXTENSIONS_GLOB}")
+        file_list.include("{lib,ext}/#{name}/**/README*")
+        file_list.exclude(%r{/extconf.rb$|/test/(?!unit)|/tests/|/sample|/demo/})
+        file_list.to_a
+      end
+    end
+  end
+end