doc 0.0.0.0 → 0.0.1

data/README.markdown

@@ -1,6 +1,85 @@
 # doc
 
-Successor of sdoc_all.
+Get searchable documentation for ruby, rails, gems, plugins and all other ruby code in one place.
+
+Successor of [sdoc_all](https://github.com/toy/sdoc_all).
+
+## Usage
+
+    sudo gem install doc
+    docr <place for your documentation>; cd <place for your documentation>
+    <your favorite editor> Rakefile
+    rake build
+    open public/index.html # that's true for mac
+
+## Config
+
+    doc.title 'ruby, rails, gems'
+    doc.min_update_interval 1.week
+    doc.clean_after 1.day
+    doc.public_dir 'pub'
+
+    doc.ruby 'ruby', 'ruby1.9', :except => %w[win32ole tk], :index => 'ruby_quick_ref'
+    doc.rails 2, 3, :prerelease => true
+    doc.gems :except => %w[
+      mysql
+      rails railties actionmailer actionpack activemodel activerecord activeresource activesupport
+      yard keychain_services msgpack doc
+    ], :prerelease => true
+    doc.paths '~/.plugins/*', :main => 'README*', :file_list => %w[+lib +README* +CHANGELOG*], :title => proc{ |path| "plugin #{path.basename}" }
+    doc.paths '~/var/ruby', :file_list => %w[+**/*.rb -_arc]
+
+### Global options
+
+- `title` for documentation title, default is 'ruby documentation'
+- `min_update_interval` — time between code updates, now used only for ruby source, default is 1 hour
+- `clean_after` — delete old generated documentation after this period of time, by default it is not set and no cleaning is made
+- `public_dir` — specify custom dir for final documentation, 'public' by default
+
+`ruby`, `rails`, `gems`, `paths` — documentation configurators, below their options are explained, all configurators have default option which can be specified without key syntax
+
+`gem` and `path` are just aliases to `gems` and `paths`
+
+### ruby
+
+Specify what to document using:
+
+- `source`: path to ruby source
+- `archive`: path to archive with ruby source (bzipped tar, gzipped tar or zip)
+- `version`: ruby version in form X.Y, X.Y.Z or X.Y.Z-pPPP. Source will be downloaded from github.com/ruby/ruby or ruby-lang.org
+- `binary`: command which is asked to run code to automatically determine ruby version. Source will be downloaded as for version specifier
+
+All those specifiers accepts multiple entries. Default option is `binary`, 'ruby' binary is used if version is not specified.
+
+Other options:
+
+- `format`: can be `:all` to simply document all code, `:separate` to build core documentation and stdlib documentation separately and `:integrate` to integrate all stdlib to core
+- `except`: skip documenting certain parts (like `win32ole` and `tk`)
+- `index`: specify folder containing index.html to replace front page. Good place for cheat sheet or quick ref like one downloaded from [zenspider](http://www.zenspider.com/Languages/Ruby/QuickRef.html).
+
+### rails
+
+Specify version(s) of rails to document using `:version`. Can be any part of version: 3, '3.0', '3.0.1'. That is default option so you can skip key. If version is not specified, latest found in installed gems will be used.
+
+Use `:prerelease => true` to document prerelease versions.
+
+### gems
+
+Use `:only` to document only certain gems or use `:except` to skip them from being documented. `:only` is the default option.
+
+Use `:versions => :all` if you want to document all installed versions.
+
+Use `:prerelease => true` to document prerelease versions.
+
+### paths
+
+Default option is `:glob`. Specify list of globs (or paths), documentation will be created for every path matched by glob.
+
+Use `:main` to specify main file. It is a list of file names, first one found at path will be used.
+
+Use `:file_list` to filter what to document. It can be an Array of glob string prefixed with + and - to exclude or include or a proc receiving instance of Rake::FileList.
+
+Use `:title` to specify title, it must be a proc receiving path and returning title.
 
 ## Copyright
 

data/Rakefile

@@ -6,11 +6,15 @@ name = 'doc'
 
 Jeweler::Tasks.new do |gem|
   gem.name = name
-  gem.summary = %Q{Documentation for everything}
-  gem.description = %Q{Command line tool to get searchable documentation for ruby, rails, gems, plugins and other ruby related code in one place}
+  gem.summary = %Q{Get all ruby documentation in one place}
+  gem.description = %Q{Generate `Rakefile` with `docr` and get searchable documentation for ruby, rails, gems, plugins and all other ruby code in one place}
   gem.homepage = "http://github.com/toy/#{name}"
   gem.license = 'MIT'
   gem.authors = ['Ivan Kuchin']
+  gem.add_runtime_dependency 'sdoc', '= 0.2.20'
+  gem.add_runtime_dependency 'fspath'
+  gem.add_runtime_dependency 'progress'
+  gem.add_runtime_dependency 'net-ftp-list'
   gem.add_development_dependency 'jeweler', '~> 1.5.1'
   gem.add_development_dependency 'rake-gem-ghost'
 end

data/VERSION

@@ -1 +1 @@
-0.0.0.0
+0.0.1

data/bin/docr

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+
+require 'pathname'
+
+case
+when %w[-v --version].include?(ARGV.first)
+  puts "#{File.basename($0)} #{(Pathname(__FILE__) + '../../VERSION').read}"
+  exit
+when %w[-h --help].include?(ARGV.first) || ARGV.length != 1
+  puts "#{File.basename($0)} dir_name"
+  exit
+else
+  dir = Pathname(ARGV.first)
+  dir.mkpath
+
+  rakefile_path = dir + 'Rakefile'
+  rakefile_data = <<-RUBY
+require 'doc'
+
+Doc::Tasks.new do |doc|
+  doc.title 'ruby, rails, gems'
+  doc.min_update_interval 1.week
+
+  doc.ruby
+  doc.rails
+  doc.gems :except => %w[mysql rails actionmailer actionpack activerecord activeresource activesupport]
+end
+  RUBY
+
+  if rakefile_path.exist? && rakefile_path.read != rakefile_data
+    puts 'Rakefile exists, overwrite?'
+    abort unless %w[o y].include?(STDIN.gets.strip.downcase[0, 1])
+  end
+
+  (dir + 'Rakefile').open('w') do |f|
+    f.write rakefile_data
+  end
+
+  puts %{Next steps:}
+  puts %{  cd "#{dir}"}
+  puts %{  #{ENV['EDITOR'] || 'vim'} Rakefile}
+  puts %{  rake build}
+end

data/doc.gemspec

@@ -4,13 +4,14 @@
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
-  s.name = %q{doc}
-  s.version = "0.0.0.0"
+  s.name = "doc"
+  s.version = "0.0.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Ivan Kuchin"]
-  s.date = %q{2010-12-16}
-  s.description = %q{Command line tool to get searchable documentation for ruby, rails, gems, plugins and other ruby related code in one place}
+  s.date = "2011-10-04"
+  s.description = "Generate `Rakefile` with `docr` and get searchable documentation for ruby, rails, gems, plugins and all other ruby code in one place"
+  s.executables = ["docr"]
   s.extra_rdoc_files = [
     "LICENSE.txt",
     "README.markdown"
@@ -21,27 +22,59 @@ Gem::Specification.new do |s|
     "README.markdown",
     "Rakefile",
     "VERSION",
+    "bin/docr",
     "doc.gemspec",
-    "lib/doc.rb"
+    "lib/doc.rb",
+    "lib/doc/base_task.rb",
+    "lib/doc/builder.rb",
+    "lib/doc/command.rb",
+    "lib/doc/config_error.rb",
+    "lib/doc/config_object.rb",
+    "lib/doc/configurator.rb",
+    "lib/doc/configurator/gems.rb",
+    "lib/doc/configurator/paths.rb",
+    "lib/doc/configurator/rails.rb",
+    "lib/doc/configurator/ruby.rb",
+    "lib/doc/configurator/ruby/path_info.rb",
+    "lib/doc/configurator/ruby/source.rb",
+    "lib/doc/configurator/ruby/stdlib.rb",
+    "lib/doc/configurator/ruby/version_specifier.rb",
+    "lib/doc/core_ext.rb",
+    "lib/doc/documentor.rb",
+    "lib/doc/merger.rb",
+    "lib/doc/root_config.rb",
+    "lib/doc/root_merger.rb",
+    "lib/doc/tasks.rb"
   ]
-  s.homepage = %q{http://github.com/toy/doc}
+  s.homepage = "http://github.com/toy/doc"
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.7}
-  s.summary = %q{Documentation for everything}
+  s.rubygems_version = "1.8.10"
+  s.summary = "Get all ruby documentation in one place"
 
   if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<sdoc>, ["= 0.2.20"])
+      s.add_runtime_dependency(%q<fspath>, [">= 0"])
+      s.add_runtime_dependency(%q<progress>, [">= 0"])
+      s.add_runtime_dependency(%q<net-ftp-list>, [">= 0"])
       s.add_development_dependency(%q<jeweler>, ["~> 1.5.1"])
       s.add_development_dependency(%q<rake-gem-ghost>, [">= 0"])
     else
+      s.add_dependency(%q<sdoc>, ["= 0.2.20"])
+      s.add_dependency(%q<fspath>, [">= 0"])
+      s.add_dependency(%q<progress>, [">= 0"])
+      s.add_dependency(%q<net-ftp-list>, [">= 0"])
       s.add_dependency(%q<jeweler>, ["~> 1.5.1"])
       s.add_dependency(%q<rake-gem-ghost>, [">= 0"])
     end
   else
+    s.add_dependency(%q<sdoc>, ["= 0.2.20"])
+    s.add_dependency(%q<fspath>, [">= 0"])
+    s.add_dependency(%q<progress>, [">= 0"])
+    s.add_dependency(%q<net-ftp-list>, [">= 0"])
     s.add_dependency(%q<jeweler>, ["~> 1.5.1"])
     s.add_dependency(%q<rake-gem-ghost>, [">= 0"])
   end

data/lib/doc.rb

@@ -0,0 +1,11 @@
+require 'doc/core_ext'
+
+module Doc
+  smart_autoload :Tasks, :Documentor, :Configurator, :ConfigObject, :RootConfig, :ConfigError
+  smart_autoload :BaseTask, :Builder, :Merger, :RootMerger
+  smart_autoload :Command
+end
+
+glob_require 'doc/configurator/*.rb'
+
+# TODO: kill sdoc_all hehe >:->

data/lib/doc/base_task.rb

@@ -0,0 +1,76 @@
+require 'digest/sha2'
+
+module Doc
+  class BaseTask
+    attr_reader :documentor, :title, :dir_name, :config
+    def initialize(documentor, options)
+      @documentor = documentor
+      @title = options[:title].to_s
+      @dir_name = options[:dir_name].to_s
+      doc_dir.touch if doc_dir.exist?
+    end
+
+    def doc_dir
+      documentor.docs_dir / dir_name
+    end
+
+    def self.state_methods(name, data_code_for_state)
+      class_eval <<-RUBY, __FILE__, __LINE__
+        def #{name}_state
+          @#{name}_state ||= #{data_code_for_state}
+        end
+        def #{name}_state_path
+          doc_dir / '.#{name}_state'
+        end
+        def #{name}_state_changed?
+          !#{name}_state_path.exist? || Marshal.load(#{name}_state_path.read) != #{name}_state
+        rescue true
+        end
+        def write_#{name}_state
+          #{name}_state_path.write(Marshal.dump(#{name}_state))
+        end
+      RUBY
+    end
+
+    state_methods :config, <<-RUBY
+      @config
+    RUBY
+
+    def hash
+      config.hash
+    end
+    def eql?(other)
+      config.eql?(other.config)
+    end
+
+    def control_files_exist?
+      %w[created.rid index.html].all? do |name|
+        (doc_dir / name).exist?
+      end
+    end
+
+    def run?
+      config_state_changed? || !control_files_exist?
+    end
+
+    abstract_method :build
+    def run(force = false)
+      if force || run?
+        doc_dir.rmtree_verbose if doc_dir.exist?
+        build
+        write_config_state
+        @state = control_files_exist? ? :succeeded : :failed
+      end
+    rescue SystemExit
+      @state = :failed
+    end
+
+    def succeeded?
+      @state == :succeeded
+    end
+
+    def failed?
+      @state == :failed
+    end
+  end
+end

data/lib/doc/builder.rb

@@ -0,0 +1,101 @@
+require 'find'
+
+module Doc
+  class Builder < BaseTask
+    attr_reader :index, :main, :source_dir, :paths
+    def initialize(documentor, options)
+      super
+      @index = options[:index].to_s if options[:index]
+      @main = options[:main].to_s if options[:main]
+      @source_dir = FSPath(options[:source_dir]).expand_path if options[:source_dir]
+      @paths = Array(options[:paths]) if options[:paths]
+
+      unless @source_dir || @paths
+        raise 'both source_dir and paths are not set'
+      end
+
+      if @paths
+        if @source_dir && !options[:no_auto_add_paths]
+          children = @source_dir.children.select(&:file?).map(&:basename).map(&:to_s)
+          @paths = children.grep(/^((mit-)?license|change(?:s|log)|readme|history|todo|copying|faq|legal)($|\.)/i) | @paths
+        end
+
+        if @main
+          unless @paths.include?(@main)
+            @paths = [@main] | @paths
+          end
+        else
+          %w[^ /].map do |prefix|
+            [/#{prefix}readme(?:\.(?:txt|rdoc|markdown|md))?$/i, /#{prefix}readme\./i]
+          end.flatten.each do |readme_r|
+            break if @main = @paths.grep(readme_r).first
+          end
+        end
+
+        @paths.select! do |path|
+          source_dir ? (source_dir / path).readable? : File.readable?(path)
+        end
+        @paths.uniq!
+
+        unless @source_dir
+          if @source_dir = FSPath.common_dir(*@paths)
+            @paths = @paths.map{ |path| FSPath(path).relative_path_from(@source_dir).to_s }
+          end
+        end
+      end
+
+      chdir_source_dir do
+        paths_info = []
+        if paths
+          Find.find(*paths) do |path|
+            paths_info << [path, File.size(path), File.mtime(path).to_i]
+          end
+        end
+
+        @config = {
+          :title => title,
+          :dir_name => dir_name,
+          :index => index,
+          :main => main,
+          :source_dir => source_dir.to_s,
+          :paths => paths_info,
+        }
+      end
+    end
+
+    def build
+      cmd = Command.new('sdoc')
+      cmd.add '--format=shtml'
+      cmd.add '--template=direct'
+      cmd.add '--line-numbers'
+      cmd.add '--all'
+      cmd.add '--charset=utf-8'
+      cmd.add '--tab-width=2'
+      cmd.add "--title=#{title}"
+      cmd.add "--output=#{doc_dir}"
+      cmd.add "--main=#{main}" if main
+      cmd.add *paths if paths
+
+      chdir_source_dir do
+        cmd.run
+      end
+
+      if control_files_exist? && index
+        index_dir_name = 'custom_index'
+        FileUtils.cp_r(index, doc_dir / index_dir_name)
+        index_html = doc_dir / 'index.html'
+        index_html.write(index_html.read.sub(/(<frame src=")[^"]+(" name="docwin" \/>)/, "\\1#{index_dir_name}/index.html\\2"))
+      end
+    end
+
+  private
+
+    def chdir_source_dir(&block)
+      if source_dir
+        Dir.chdir(source_dir, &block)
+      else
+        block.call
+      end
+    end
+  end
+end

data/lib/doc/command.rb

@@ -0,0 +1,40 @@
+require 'shellwords'
+
+module Doc
+  class Command
+    def self.run(*command)
+      new(*command).run
+    end
+
+    attr_reader :command, :status
+    def initialize(*command)
+      @command = command
+    end
+
+    def add(*arguments)
+      @command.concat(arguments)
+    end
+
+    def run
+      command_string = command.length == 1 ? command.first : command.map(&:to_s).shelljoin
+      puts "cd #{Dir.pwd.shellescape}; #{command_string}"
+      output = IO.popen("#{command_string} 2>&1", &:read)
+      @status = $?
+      status.success? || begin
+        print output
+        case
+        when status.signaled?
+          if status.termsig == 2
+            raise Interrupt.new
+          else
+            raise SignalException.new(status.termsig)
+          end
+        when status.exited?
+          raise SystemExit.new(status.exitstatus)
+        else
+          raise status.inspect
+        end
+      end
+    end
+  end
+end