sdoc_all 0.1.0 → 0.2.0.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Boba Fat
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest

@@ -1,17 +1,27 @@
 bin/sdoc-all
 lib/sdoc_all/base.rb
+lib/sdoc_all/config_error.rb
 lib/sdoc_all/gems.rb
 lib/sdoc_all/generator/sdoc_all/sdoc_all_generator.rb
+lib/sdoc_all/generator/sdoc_all/templates/config.yml
 lib/sdoc_all/generator/sdoc_all/templates/Rakefile
-lib/sdoc_all/generator/sdoc_all/templates/sdoc.config.yml.erb
+lib/sdoc_all/paths.rb
 lib/sdoc_all/plugins.rb
 lib/sdoc_all/rails.rb
-lib/sdoc_all/rdoc_task.rb
-lib/sdoc_all/rdoc_tasks.rb
 lib/sdoc_all/ruby.rb
+lib/sdoc_all/task.rb
 lib/sdoc_all.rb
-lib/tasks/sdoc_all.rb
+lib/tasks/sdoc_all_rake.rb
+LICENSE
 Manifest
 Rakefile
 README.rdoc
+spec/sdoc_all/gems_spec.rb
+spec/sdoc_all/paths_spec.rb
+spec/sdoc_all/plugins_spec.rb
+spec/sdoc_all/rails_spec.rb
+spec/sdoc_all/ruby_spec.rb
+spec/sdoc_all_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
 VERSION.yml

data/README.rdoc

@@ -1,23 +1,134 @@
 = sdoc-all
-Command line tool to get documentation for ruby, rails, gems and plugins in one place
+Command line tool to get documentation for ruby, rails, gems, plugins and other ruby code in one place
 
 == Getting Started
-  sudo gem install sdoc sdoc_all
+  sudo gem install voloko-sdoc sdoc_all
   sdoc-all <place for your documentation>; cd <place for your documentation>
-  rake update
-
-== Configure
-in <tt>sdoc.config.yml</tt> you can define:
-- preferred version of ruby
-- preferred version of rails
-- plugins directory
-- what to exclude
-
-== How it works
-sdoc-all generates folder with config and rakefile
-running <tt>rake update</tt> (or simply <tt>rake</tt> as it is default task) in that folder:
-- downloads ruby sources from ftp.ruby-lang.org
-- builds dummy rails applications and freezes gems there
-- builds documentation for ruby, rails, gems and plugins
-- merges documentation
-rerunning rake rebuilds only changed files if not asked to rebuild everything (force in config)
+  <your favorite editor> config.yml
+  rake run
+
+== config.yml
+
+=== example
+  ---
+  min_update_interval: 1 hour
+  sdoc:
+  - ruby: 1.8.7
+  - rails
+  - gems:
+      exclude:
+      - mysql
+      - rails
+      - actionmailer
+      - actionpack
+      - activerecord
+      - activeresource
+      - activesupport
+  - plugins: ~/.plugins
+  - path: ~/some/path
+
+=== options
+time to skip updates (for now ruby and plugins are updated)
+days, hours, minutes, seconds accepted
+  min_update_interval: 1 hour
+
+list of things you want to document
+carefully watch indent - 4 spaces for options
+  sdoc:
+
+=== ruby
+ruby 1.8.6 source will be downloaded for you from ftp.ruby-lang.org and placed in folder sources
+  - ruby: 1.8.6
+
+if you don't want updates use this
+  - ruby:
+      version: 1.8.6
+      update: false
+
+=== rails
+choose rails version
+  - rails: 2.3.2
+
+latest installed version will be used
+  - rails
+
+=== gems
+document all gems
+  - gems
+
+document nokogiri and hpricot gems
+  - gems: [nokogiri, hpricot]
+
+document nokogiri gem (gem is just an alias to gems)
+  - gem: nokogiri
+
+document all installed versions of nokogiri and hpricot gems (not latest)
+  - gems:
+      only: [nokogiri, hpricot]
+      versions: all
+
+document all gems except mysql and gems related to rails
+  - gems:
+      exclude:
+      - mysql
+      - rails
+      - actionmailer
+      - actionpack
+      - activerecord
+      - activeresource
+      - activesupport
+
+=== plugins
+document plugins in folder ~/.plugins (they will also be updated if they are under git)
+  - plugins: ~/.plugins
+
+document plugins in folder sources/plugins
+  - plugins
+
+document only dump plugin
+  - plugin:
+      path: ~/.plugins
+      only: dump
+
+document dump, access and data_columns plugins
+  - plugins:
+      path: ~/.plugins
+      only: [dump, access, data_columns]
+
+don't update plugins under git
+  - plugins:
+      path: ~/.plugins
+      update: false
+
+document all plugins except acts_as_fu and acts_as_bar
+  - plugins:
+      path: ~/.plugins
+      exclude: [acts_as_fu, acts_as_bar]
+
+=== paths
+document file or directory (you can create .document file in directory to tell rdoc what to document)
+  - path: ~/lib/bin
+
+it can be a glob (each entry will be documented separately)
+  - paths: ~/lib/*
+
+or array (note that name of documentation for each will be relative path from common ancestor)
+  - paths: [~/lib/*, ~/scripts/**, /test.rb, /rm-rf.rb]
+
+if you want to specify more options (roots are not globed in this form)
+  - paths:
+      root: ~/lib/app
+      main: README
+      paths: [+*, +lib/*.rb, +tasks/*.rake, -*.sw*, -OLD_README]
+
+or array form (mixed type)
+  - paths:
+    - root: ~/lib/app
+      main: SUPAREADME
+      paths: [+*, +lib/*.rb, +tasks/*.rake, -*.sw*, -OLD_README]
+    - ~/lib/app2
+    - root: ~/lib/app3
+      main: SUPAREADME
+    - root: ~/lib/app3
+      paths: *.rb
+    - ~/lib/old/app*

data/Rakefile

@@ -9,8 +9,13 @@ version = YAML.load_file(File.join(File.dirname(__FILE__), 'VERSION.yml')).join(
 
 Echoe.new('sdoc_all', version) do |p|
   p.author = "toy"
-  p.summary = "Command line tool to get documentation for ruby, rails, gems and plugins in one place"
+  p.summary = "documentation for everything"
+  p.description = "Command line tool to get documentation for ruby, rails, gems and plugins in one place"
+  p.email = "ivan@workisfun.ru"
   p.url = "http://github.com/toy/sdoc_all"
-  p.runtime_dependencies = %w(sdoc activesupport rake progress)
+  p.runtime_dependencies << 'activesupport'
+  p.runtime_dependencies << 'rake'
+  p.runtime_dependencies << 'progress >= 0.0.8'
+  # TODO: sdoc or voloko-sdoc
   p.project = 'toytoy'
 end

data/VERSION.yml

@@ -1 +1 @@
-[0, 1, 0]
+[0, 2, 0, 1]

data/bin/sdoc-all

@@ -5,7 +5,7 @@ require 'rubigen'
 
 if %w(-v --version).include? ARGV.first
   version = YAML.load_file(File.join(File.dirname(__FILE__), '../VERSION.yml'))
-  puts "#{File.basename($0)} #{version[:major]}.#{version[:minor]}.#{version[:patch]}"
+  puts "#{File.basename($0)} #{version.join('.')}"
   exit(0)
 end
 

data/lib/sdoc_all/base.rb

@@ -1,80 +1,123 @@
 class SdocAll
   class Base
-    def self.inherited(subclass)
-      (@subclasses ||= []) << subclass
+    attr_reader :config
+
+  protected
+
+    def raise_unknown_options_if_not_blank!(config)
+      unless config.blank?
+        raise ConfigError.new("unknown options for \"#{self.class.short_name}\": #{config.inspect}")
+      end
     end
 
-    def self.update_all_sources(options = {})
-      options[:sources_path].mkpath
-      Dir.chdir(options[:sources_path]) do
-        @subclasses.each do |subclass|
-          subclass.update_sources(options)
-        end
+    def config_only_option(config)
+      if only = config.delete(:only)
+        [only].flatten.map(&:to_s).map(&:downcase)
       end
     end
 
-    def self.rdoc_tasks(options = {})
-      Dir.chdir(options[:sources_path]) do
-        @@tasks = RdocTasks.new
+    def config_exclude_option(config)
+      if exclude = config.delete(:exclude)
+        [exclude].flatten.map(&:to_s).map(&:downcase)
+      else
+        []
+      end
+    end
 
-        @subclasses.each do |subclass|
-          subclass.add_rdoc_tasks(options)
-        end
+    def sources_path
+      self.class.sources_path
+    end
+
+    module ClassMethods
+      BASE_PATH = Pathname.new(Dir.pwd).expand_path
+      DOCS_PATH = BASE_PATH + 'docs'
+      PUBLIC_PATH = BASE_PATH + 'public'
 
-        to_clear = Dir.glob(options[:docs_path] + '*/*')
-        @@tasks.each do |task|
-          doc_path = options[:docs_path] + task.doc_path
-          to_clear.delete_if{ |path| path.starts_with?(doc_path) }
+      def base_path
+        BASE_PATH
+      end
+
+      def docs_path
+        DOCS_PATH.tap(&:mkpath)
+      end
+
+      def public_path
+        PUBLIC_PATH
+      end
+
+      def subclasses
+        @subclasses ||= {}
+      end
+
+      def short_name
+        name.demodulize.underscore
+      end
+
+      def sources_path
+        Pathname.new("sources/#{short_name}").tap do |path|
+          path.mkpath
         end
-        to_clear.each do |path|
-          remove_if_present(path)
+      end
+
+      def inherited(subclass)
+        name = subclass.short_name
+        [name, name.singularize, name.pluralize].uniq.each do |name_form|
+          subclasses[name_form] = subclass
         end
+      end
 
-        @@tasks.each do |task|
-          doc_path = options[:docs_path] + task.doc_path
-
-          begin
-            raise 'force' if options[:force]
-            if File.exist?(doc_path)
-              unless File.directory?(doc_path)
-                raise 'not a dir'
-              else
-                created = Time.parse(File.read(doc_path + 'created.rid'))
-                Find.find(options[:sources_path] + task.src_path) do |path|
-                  Find.prune if File.directory?(path) && File.basename(path)[0] == ?.
-                  raise "changed #{path}" if File.ctime(path) > created || File.mtime(path) > created
-                end
-              end
-            end
-          rescue => e
-            puts e
-            remove_if_present(doc_path)
-          end
+      def entries
+        @entries ||= []
+      end
+
+      def clear
+        entries.clear
+      end
+
+      def to_document(type, config)
+        type = type.to_s
+        config.symbolize_keys! if config.is_a?(Hash)
+        if subclasses[type]
+          entries << subclasses[type].new(config)
+        else
+          raise ConfigError.new("don't know how to build \"#{type}\" => #{config.inspect}")
         end
+      end
 
+      def tasks(options = {})
+        @@tasks = []
+        entries.each do |entry|
+          entry.add_tasks(options)
+        end
         @@tasks
       end
-    end
 
-  protected
+      def add_task(options = {})
+        options[:paths] ||= []
+        [/^readme$/i, /^readme\.(?:txt|rdoc|markdown)$/i, /^readme\./i].each do |readme_r|
+          options[:main] ||= options[:paths].grep(readme_r).first
+        end
+        @@tasks << Task.new(options)
+      end
 
-    def self.add_rdoc_task(options = {})
-      options[:pathes] ||= []
-      [/^readme$/i, /^readme\.(?:txt|rdoc|markdown)$/i, /^readme\./i].each do |readme_r|
-        options[:main] ||= options[:pathes].grep(readme_r).first
+      def system(*args)
+        escaped_args = args.map(&:to_s).map{ |arg| arg[/[^a-z0-9\/\-.]/i] ? arg.inspect : arg }
+        command = escaped_args.join(' ')
+        puts "Executing #{command.length > 250 ? "#{command[0, 247]}..." : command}"
+        Kernel.system(*args)
       end
-      @@tasks.add(self, options)
-    end
 
-    def self.with_env(key, value)
-      old_value, ENV[key] = ENV[key], value
-      yield
-    ensure
-      ENV[key] = old_value
-    end
+      def remove_if_present(path)
+        FileUtils.remove_entry(path) if File.exist?(path)
+      end
 
-    def self.remove_if_present(path)
-      FileUtils.remove_entry(path) if File.exist?(path)
+      def with_env(key, value)
+        old_value, ENV[key] = ENV[key], value
+        yield
+      ensure
+        ENV[key] = old_value
+      end
     end
+    extend ClassMethods
   end
 end

data/lib/sdoc_all/config_error.rb

@@ -0,0 +1,4 @@
+class SdocAll
+  class ConfigError < Exception
+  end
+end

data/lib/sdoc_all/gems.rb

@@ -1,28 +1,54 @@
-require 'enumerator'
-
 class SdocAll
   class Gems < Base
-    def self.each(&block)
-      Gem.source_index.each(&block)
-    end
+    def initialize(config)
+      config ||= {}
+      config = {:only => config} unless config.is_a?(Hash)
+
+      @config = {
+        :versions => config.delete(:versions).to_s.downcase,
+        :only => config_only_option(config),
+        :exclude => config_exclude_option(config),
+      }
 
-    def self.update_sources(options = {})
+      raise_unknown_options_if_not_blank!(config)
     end
 
-    def self.add_rdoc_tasks(options = {})
-      each do |gem_name, spec|
+    def add_tasks(options = {})
+      specs = config[:versions] == 'all' ? self.class.all_specs : self.class.latest_specs
+
+      specs.sort_by!{ |spec| [spec.name.downcase, spec.sort_obj] }
+
+      specs.delete_if{ |spec| !config[:only].include?(spec.name.downcase) } if config[:only]
+      specs.delete_if{ |spec| config[:exclude].include?(spec.name.downcase) }
+
+      specs.each do |spec|
         main = nil
         spec.rdoc_options.each_cons(2) do |options|
           main = options[1] if %w(--main -m).include?(options[0])
         end
-        add_rdoc_task(
-          :name_parts => [spec.name, spec.version],
+        Base.add_task(
           :src_path => spec.full_gem_path,
-          :doc_path => "gems/#{gem_name}",
-          :pathes => spec.require_paths + spec.extra_rdoc_files,
-          :main => main
+          :doc_path => "gems.#{spec.full_name}",
+          :paths => spec.require_paths + spec.extra_rdoc_files,
+          :main => main,
+          :title => "gems: #{spec.full_name}"
         )
       end
     end
+
+    module ClassMethods
+      def latest_specs
+        Gem.source_index.latest_specs
+      end
+
+      def all_specs
+        specs = []
+        Gem.source_index.each do |_, spec|
+          specs << spec
+        end
+        specs
+      end
+    end
+    extend ClassMethods
   end
 end

data/lib/sdoc_all/generator/sdoc_all/sdoc_all_generator.rb

@@ -16,12 +16,7 @@ class SdocAllGenerator < RubiGen::Base
       BASEDIRS.each { |path| m.directory path }
 
       m.file_copy_each %w(Rakefile)
-      m.template_copy_each %w(sdoc.config.yml.erb), nil, :assigns => {:sdoc_options => {
-        'ruby' => options[:ruby],
-        'rails' => options[:rails],
-        'exclude' => options[:exclude],
-        'plugins_path' => options[:plugins_path],
-      }}
+      m.file_copy_each %w(config.yml)
     end
   end
 
@@ -46,11 +41,6 @@ EOS
       opts.separator ''
       opts.separator 'Options:'
 
-      opts.on("-r", "--ruby=\"version\"", String, "version of ruby you want to be documented like 1.8 or 1.8.6", "Default: latest") { |o| options[:ruby] = o }
-      opts.on("-a", "--rails=\"version\"", String, "version of rails you want to be documented like 2. or 2.3.2", "Default: latest") { |o| options[:rails] = o }
-      opts.on("-e", "--exclude=\"pathes\"", Array, "what to exclude separated with comma like gems/actionmailer or gems/actionpack,gems/rails", "Default: gems related to rails") { |o| options[:exclude] = o }
-      opts.on("-p", "--plugins_path=\"path\"", Array, "directory in which you store plugins you use are stored", "Default: ~/.plugins") { |o| options[:plugins_path] = o }
-
       opts.on("-v", "--version", "Show the #{File.basename($0)} version number and quit.")
     end
 

data/lib/sdoc_all/generator/sdoc_all/templates/Rakefile

@@ -1,4 +1,6 @@
 require 'rubygems'
+require 'rake'
 require 'sdoc'
+require 'sdoc_all'
 
-require 'tasks/sdoc_all'
+require 'tasks/sdoc_all_rake'

data/lib/sdoc_all/generator/sdoc_all/templates/config.yml

@@ -0,0 +1,16 @@
+---
+min_update_interval: 1 hour
+sdoc: # watch indent in this section - it must be 4 spaces
+- ruby: 1.8.7
+- rails
+- gems:
+    exclude:
+    - mysql
+    - rails
+    - actionmailer
+    - actionpack
+    - activerecord
+    - activeresource
+    - activesupport
+- plugins: ~/.plugins
+# - path: ~/some/path

data/lib/sdoc_all/paths.rb

@@ -0,0 +1,100 @@
+class SdocAll
+  class Paths < Base
+    def initialize(config)
+      config = [config] unless config.is_a?(Array)
+
+      config.each do |entry|
+        case entry
+        when Hash
+          entry.symbolize_keys!
+
+          unless entry[:root].present?
+            raise ConfigError.new("specify what to document")
+          end
+
+          root = Pathname.new(entry.delete(:root)).expand_path
+
+          unless root.exist?
+            raise ConfigError.new("path #{root} does not exist")
+          end
+
+          paths = entry.delete(:paths)
+          paths = [paths] if paths && !paths.is_a?(Array)
+
+          entries << {
+            :root => root,
+            :main => entry.delete(:main),
+            :paths => paths,
+          }
+          raise_unknown_options_if_not_blank!(entry)
+        when String
+          Dir[File.expand_path(entry)].each do |path|
+            config << {:root => path}
+          end
+        else
+          raise_unknown_options_if_not_blank!(entry)
+        end
+      end
+    end
+
+    def add_tasks(options = {})
+      common_path = self.class.common_path(entries.map{ |entry| entry[:root] })
+
+      entries.each do |entry|
+        path = entry[:root]
+
+        task_options = {
+          :src_path => path,
+          :doc_path => "paths.#{path.relative_path_from(common_path).to_s.gsub('/', '.')}",
+        }
+        task_options[:title] = task_options[:doc_path].sub('.', ': ')
+        task_options[:main] = entry[:main] if entry[:main]
+
+        if entry[:paths]
+          paths = Rake::FileList.new
+          Dir.chdir(path) do
+            entry[:paths].each do |glob|
+              m = /^([+-]?)(.*)$/.match(glob)
+              if m[1] == '-'
+                paths.exclude(m[2])
+              else
+                paths.include(m[2])
+              end
+            end
+            paths.resolve
+          end
+
+          task_options[:paths] = paths.to_a
+        end
+
+        Base.add_task(task_options)
+      end
+    end
+
+  private
+
+    def entries
+      @entries ||= []
+    end
+
+    module ClassMethods
+      def common_path(paths)
+        common = nil
+        paths.each do |path|
+          if common ||= path
+            unless path.to_s.starts_with?(common.to_s)
+              path.ascend do |path_part|
+                if common.to_s.starts_with?(path_part)
+                  common = path_part
+                  break
+                end
+              end
+            end
+          end
+        end
+        common = common.parent if common
+      end
+    end
+    extend ClassMethods
+  end
+end