rdoc-rake 1.0

data/.autotest

@@ -0,0 +1,17 @@
+# -*- ruby -*-
+
+require 'autotest/restart'
+
+Autotest.add_hook :initialize do |at|
+  at.libs << ':../trunk/lib'
+  at.testlib = 'minitest/unit'
+
+  def at.path_to_classname(s)
+    sep = File::SEPARATOR
+    f = s.sub(/^test#{sep}/, '').sub(/\.rb$/, '').split(sep)
+    f = f.map { |path| path.split(/_|(\d+)/).map { |seg| seg.capitalize }.join }
+    f = f.map { |path| path =~ /^Test/ ? path : "Test#{path}"  }
+    f.join('::').sub 'Rdoc', 'RDoc'
+  end
+end
+

data/History.txt

@@ -0,0 +1,6 @@
+=== 1.0.0 / 2010-04-19
+
+* 1 major enhancement
+
+  * Birthday!
+

data/Manifest.txt

@@ -0,0 +1,8 @@
+.autotest
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/rdoc/discover.rb
+lib/rdoc/parser/rake.rb
+test/test_rdoc_parser_rake.rb

data/README.txt

@@ -0,0 +1,50 @@
+= rdoc_rake
+
+* http://rdoc.rubyforge.org/rdoc-rake
+
+== DESCRIPTION:
+
+RDoc plugin for documenting rake tasks
+
+== FEATURES/PROBLEMS:
+
+* Little special handling for HTML output
+* Probably inaccessible via ri (but why?)
+
+== SYNOPSIS:
+
+  gem install rdoc-rake
+  rdoc lib Rakefile README.txt --main README.txt
+
+== REQUIREMENTS:
+
+* rdoc 2.5+
+
+== INSTALL:
+
+* gem install rdoc-rake
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2010 Eric Hodel
+
+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/Rakefile

@@ -0,0 +1,17 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require 'hoe/git'
+
+Hoe.add_include_dirs '../trunk/lib'
+
+Hoe.spec 'rdoc-rake' do
+  self.rubyforge_name = 'rdoc'
+  developer 'Eric Hodel', 'drbrain@segment7.net'
+
+  extra_deps       << ['rdoc', '~> 2.5']
+  extra_rdoc_files << 'Rakefile'
+end
+
+# vim: syntax=Ruby

data/lib/rdoc/discover.rb

@@ -0,0 +1,2 @@
+require 'rdoc/parser/rake'
+

data/lib/rdoc/parser/rake.rb

@@ -0,0 +1,309 @@
+require 'rdoc/parser/ruby'
+
+##
+# Maps task builders like Hoe or RDoc::Task to an RDoc::Include
+
+class RDoc::RakeBuilder < RDoc::Include
+end
+
+##
+# Maps a Rake namespace to an RDoc::NormalModule
+
+class RDoc::RakeNamespace < RDoc::NormalModule
+end
+
+##
+# Maps a Rake::Task to an RDoc::AnyMethod
+
+class RDoc::RakeTask < RDoc::AnyMethod
+
+  attr_accessor :dependencies
+
+  def initialize(*args)
+    super
+    @dependencies = []
+  end
+
+end
+
+##
+# An RDoc parser for Rakefiles.
+
+class RDoc::Parser::Rake < RDoc::Parser
+
+  VERSION = '1.0'
+
+  include RDoc::RubyToken
+  include RDoc::TokenStream
+  include RDoc::Parser::RubyTools
+
+  parse_files_matching(/Rakefile(\.rb)?$/i)
+  parse_files_matching(/\.rake$/)
+
+  def initialize(top_level, file_name, content, options, stats)
+    super
+
+    @size = 0
+    @token_listeners = nil
+    @scanner = RDoc::RubyLex.new content, @options
+    @scanner.exception_on_syntax_error = false
+    @rake_tasks = @top_level.add_module RDoc::RakeNamespace, 'Rake Tasks'
+
+    reset
+  end
+
+  ##
+  # Consumes an Array
+
+  def consume_array
+    tokens = get_tk_until TkRBRACK
+    tokens << get_tk
+    tokens
+  end
+
+  ##
+  # Consumes the body of a task
+
+  def consume_body
+    seen_nest = false
+    nest = 0
+
+    body = []
+
+    while tk = get_tk do
+      body << tk
+
+      case tk
+      when TkDO, TkCLASS, TkMODULE, TkDEF, TkBEGIN, TkIF, TkUNLESS, TkCASE,
+           TkWHILE, TkUNTIL, TkFOR then
+        nest += 1
+        seen_nest = true
+      when TkEND then
+        nest -= 1
+      when TkNL then
+        break unless seen_nest
+      end
+
+      break if nest == 0 and seen_nest
+    end
+
+    body
+  end
+
+  ##
+  # Consumes arguments to a task
+
+  def consume_task_arguments
+    skip_tkspace false
+
+    tk = get_tk
+
+    case tk
+    when TkNL, TkDO then
+      unget_tk tk
+    when TkASSIGN then
+      get_tk # finish assoc, lexer bug
+      skip_tkspace
+
+      case tk = get_tk
+      when TkLBRACK then
+        tokens = consume_array
+        tokens = tokens.select do |token| TkSYMBOL === token end
+        tokens = tokens.map do |token| token.to_sym end
+        @task.dependencies.push(*tokens)
+      when TkSYMBOL then # ok
+        @task.dependencies << tk.to_sym
+      else
+        puts :task_arg => tk
+      end
+    end
+  end
+
+  ##
+  # Parses a Rake description
+  #
+  #   desc "My cool task"
+
+  def parse_description
+    skip_tkspace
+
+    tk = get_tk
+
+    @desc = tk.text[1..-2]
+  end
+
+  ##
+  # Parses a Rake namespace
+  #
+  #   namespace "doc"
+
+  def parse_namespace
+    skip_tkspace
+
+    tk = get_tk
+
+    namespace = @container.add_module RDoc::RakeNamespace, tk.text[1..-1]
+
+    skip_tkspace
+
+    old_namespace = @container
+
+    begin
+      @nest += 1
+      @container = namespace
+
+      parse_rakefile
+    ensure
+      @container = old_namespace
+      @nest -= 1
+    end
+  end
+
+  ##
+  # Parses a Rake task
+  #
+  #   task "my_cool_task"
+
+  def parse_task(tk)
+    collect_tokens
+    add_token tk
+
+    token_listener self do
+      skip_tkspace false
+
+      tk = get_tk
+      name = tk.text
+
+      @task = @container.find_instance_method_named name
+
+      unless @task then
+        @task = RDoc::RakeTask.new tokens_to_s, name
+        @container.add_method @task
+        @stats.add_method @task
+      end
+
+      @task.comment += use_desc
+
+      consume_task_arguments
+    end
+
+    @task.collect_tokens
+    @task.add_tokens token_stream
+
+    token_listener @task do
+      consume_body
+    end
+
+    @task
+  end
+
+  ##
+  # Parses a Rake task builder
+  #
+  #   Hoe.new 'my_cool_project' do # ...
+
+  def parse_task_builder(tk)
+    name = tk.name
+
+    if 'ENV' == name then
+      get_tk_until TkNL
+      return
+    end
+
+    get_tk_until TkDO, TkNL
+
+    tk = get_tk
+
+    case tk
+    when TkDO then
+      unget_tk tk
+      consume_body
+    end
+
+    builder = RDoc::RakeBuilder.new name, ''
+
+    @container.add_include builder
+  end
+
+  ##
+  # Parses a Rakefile
+
+  def parse_rakefile
+    current_nest = @nest
+
+    while tk = get_tk do
+      case tk
+      when TkCONSTANT then
+        parse_task_builder tk
+      when TkDO then
+        @nest += 1
+      when TkEND then
+        @nest -= 1
+        break if current_nest > 0 and @nest <= current_nest
+      when TkIDENTIFIER then
+        case tk.name
+        when 'desc' then
+          parse_description
+        when 'task' then
+          parse_task(tk)
+        when 'namespace' then
+          parse_namespace
+        when 'require' then
+          parse_require
+        #else
+        #  p :ident => tk
+        end
+      when TkNL, TkSPACE then # ignore
+      #else
+      #  p :unhandled => tk
+      end
+    end
+  end
+
+  ##
+  # Adds a new RDoc::Require to the container
+
+  def parse_require
+    skip_tkspace false
+
+    tk = get_tk
+
+    name = tk.text if TkSTRING === tk
+
+    if name then
+      @container.add_require RDoc::Require.new(name, '')
+    else
+      unget_tk tk
+    end
+  end
+
+  ##
+  # Performs the work of parsing a rakefile
+
+  def scan
+    reset
+
+    @container = @rake_tasks
+
+    @stats.add_module @container
+
+    catch :eof do
+      catch :enddoc do
+        parse_rakefile
+      end
+    end
+
+    @top_level
+  end
+
+  ##
+  # Uses the last description encountered
+
+  def use_desc
+    desc = @desc
+    @desc = nil
+    desc || ''
+  end
+
+end
+

data/test/test_rdoc_parser_rake.rb

@@ -0,0 +1,276 @@
+require 'stringio'
+require 'tempfile'
+require 'rubygems'
+require 'minitest/autorun'
+
+require 'rdoc'
+require 'rdoc/options'
+require 'rdoc/parser/rake'
+
+class TestRDocParserRake < MiniTest::Unit::TestCase
+
+  def setup
+    @tempfile = Tempfile.new self.class.name
+    @filename = @tempfile.path
+
+    util_top_level
+
+    @options = RDoc::Options.new
+    @options.quiet = true
+    @stats = RDoc::Stats.new 0
+  end
+
+  def teardown
+    @tempfile.close
+  end
+
+  def test_parse_tasks
+    rakefile = <<-RAKE
+desc "my cool task"
+task :default do
+  puts "you ran my cool task!"
+end
+    RAKE
+
+    util_parser rakefile
+
+    @parser.scan
+
+    util_tasks
+    assert_equal 1, @tasks.length
+    task = @tasks.first
+
+    assert_equal ':default', task.name
+    assert_equal 'my cool task', task.comment
+    assert_equal 'task :default', task.text
+  end
+
+  def test_parse_tasks_dependency
+    rakefile = <<-RAKE
+desc "my cool task"
+task :default => :test do
+  puts "you ran my cool task!"
+end
+    RAKE
+
+    util_parser rakefile
+
+    @parser.scan
+
+    util_tasks
+    assert_equal 1, @tasks.length
+    task = @tasks.first
+
+    assert_equal ':default', task.name
+    assert_equal 'my cool task', task.comment
+
+    assert_equal 'task :default', task.text
+    assert_equal [:test], task.dependencies
+
+    expected = [
+      tk(:identifier, 2,  0, 'task', 'task'),
+      tk(:space,      2,  4, nil,    ' '),
+      tk(:symbol,     2,  5, nil,    ':default'),
+      tk(:space,      2, 13, nil,    ' '),
+      tk(:assign,     2, 14, nil,    '='),
+      tk(:gt,         2, 15, nil,    '>'),
+      tk(:space,      2, 16, nil,    ' '),
+      tk(:symbol,     2, 17, nil,    ':test'),
+      tk(:space,      2, 22, nil,    ' '),
+      tk(:do,         2, 23, 'do',   'do'),
+      tk(:nl,         2, 25, nil,    "\n"),
+      tk(:space,      3,  0, nil,    '  '),
+      tk(:identifier, 3,  2, 'puts', 'puts'),
+      tk(:space,      3,  6, nil,    ' '),
+      tk(:string,     3,  7, nil,    '"you ran my cool task!"'),
+      tk(:nl,         3, 30, nil,    "\n"),
+      tk(:end,        4,  0, 'end',  'end'),
+    ]
+
+    assert_equal expected, task.token_stream
+  end
+
+  def test_parse_tasks_dependency_only
+    rakefile = <<-RAKE
+desc "my cool task"
+task :default => :test
+
+task :test => :build
+    RAKE
+
+    util_parser rakefile
+
+    @parser.scan
+
+    util_tasks
+    assert_equal 2, @tasks.length
+    task = @tasks.first
+
+    assert_equal ':default', task.name
+    assert_equal 'my cool task', task.comment
+    assert_equal 'task :default', task.text
+    assert_equal [:test], task.dependencies
+
+    expected = [
+      tk(:identifier, 2,  0, 'task', 'task'),
+      tk(:space,      2,  4, nil,    ' '),
+      tk(:symbol,     2,  5, nil,    ':default'),
+      tk(:space,      2, 13, nil,    ' '),
+      tk(:assign,     2, 14, nil,    '='), # lexer bug
+      tk(:gt,         2, 15, nil,    '>'),
+      tk(:space,      2, 16, nil,    ' '),
+      tk(:symbol,     2, 17, nil,    ':test'),
+      tk(:nl,         2, 22, nil,    "\n"),
+    ]
+
+    assert_equal expected, task.token_stream
+  end
+
+  def test_parse_tasks_dependencies
+    rakefile = <<-RAKE
+desc "my cool task"
+task :default => [:build, :test]
+    RAKE
+
+    util_parser rakefile
+
+    @parser.scan
+
+    util_tasks
+    assert_equal 1, @tasks.length
+    task = @tasks.first
+
+    assert_equal ':default', task.name
+    assert_equal 'my cool task', task.comment
+    assert_equal 'task :default', task.text
+    assert_equal [:build, :test], task.dependencies
+  end
+
+  def test_parse_tasks_hoe
+    rakefile = <<-RAKE
+Hoe.spec 'my_cool_project' do
+  developer 'Cool Guy', 'cool_guy@example.com'
+end
+
+desc "my cool task"
+task :default do
+  puts "you ran my cool task!"
+end
+    RAKE
+
+    util_parser rakefile
+
+    @parser.scan
+
+    util_tasks
+    assert_equal 1, @tasks.length
+    task = @tasks.first
+
+    assert_equal ':default', task.name
+
+    assert_equal 1, @rake_tasks.includes.length
+    hoe = @rake_tasks.includes.first
+
+    assert_equal 'Hoe', hoe.name
+  end
+
+  def test_parse_tasks_require
+    rakefile = <<-RAKE
+require 'blah'
+    RAKE
+
+    util_parser rakefile
+
+    @parser.scan
+
+    assert_equal 1, @top_level.requires.length
+    require = @top_level.requires.first
+
+    assert_equal 'blah', require.name
+  end
+
+  def test_parse_tasks_split
+    rakefile = <<-RAKE
+desc "my cool task"
+task :default => :build
+
+task :default => :test
+    RAKE
+
+    util_parser rakefile
+
+    @parser.scan
+
+    util_tasks
+    assert_equal 1, @tasks.length
+    task = @tasks.first
+
+    assert_equal ':default', task.name
+    assert_equal 'my cool task', task.comment
+    assert_equal 'task :default', task.text
+    assert_equal [:build, :test], task.dependencies
+  end
+
+  def test_parse_tasks_namespage
+    rakefile = <<-RAKE
+desc "my cool task"
+task :default do
+  puts "you ran my cool task!"
+end
+
+namespace :cool do
+  task :awesome do
+  end
+end
+
+desc "this is another cool task"
+task :other
+    RAKE
+
+    util_parser rakefile
+
+    @parser.scan
+
+    #pp @top_level
+    util_tasks
+
+    assert_equal 2, @tasks.length
+    task = @tasks.first
+
+    assert_equal ':default', @tasks.first.name
+    assert_equal ':other',   @tasks.last.name
+  end
+
+  def tk(klass, line, char, name, text) # HACK dup
+    klass = RDoc::RubyToken.const_get "Tk#{klass.to_s.upcase}"
+
+    token = if klass.instance_method(:initialize).arity == 3 then
+              raise ArgumentError, "name not used for #{klass}" unless name.nil?
+              klass.new nil, line, char
+            else
+              klass.new nil, line, char, name
+            end
+
+    token.set_text text
+
+    token
+  end
+
+  def util_parser(content)
+    @parser = RDoc::Parser::Rake.new @top_level, @filename, content, @options,
+                                     @stats
+  end
+
+  def util_top_level
+    RDoc::TopLevel.reset
+    @top_level = RDoc::TopLevel.new @filename
+  end
+
+  def util_tasks
+    @rake_tasks = @top_level.modules.first
+
+    @tasks = @rake_tasks.method_list
+  end
+
+end
+

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification 
+name: rdoc-rake
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  version: "1.0"
+platform: ruby
+authors: 
+- Eric Hodel
+autorequire: 
+bindir: bin
+cert_chain: 
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIDNjCCAh6gAwIBAgIBADANBgkqhkiG9w0BAQUFADBBMRAwDgYDVQQDDAdkcmJy
+  YWluMRgwFgYKCZImiZPyLGQBGRYIc2VnbWVudDcxEzARBgoJkiaJk/IsZAEZFgNu
+  ZXQwHhcNMDcxMjIxMDIwNDE0WhcNMDgxMjIwMDIwNDE0WjBBMRAwDgYDVQQDDAdk
+  cmJyYWluMRgwFgYKCZImiZPyLGQBGRYIc2VnbWVudDcxEzARBgoJkiaJk/IsZAEZ
+  FgNuZXQwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCbbgLrGLGIDE76
+  LV/cvxdEzCuYuS3oG9PrSZnuDweySUfdp/so0cDq+j8bqy6OzZSw07gdjwFMSd6J
+  U5ddZCVywn5nnAQ+Ui7jMW54CYt5/H6f2US6U0hQOjJR6cpfiymgxGdfyTiVcvTm
+  Gj/okWrQl0NjYOYBpDi+9PPmaH2RmLJu0dB/NylsDnW5j6yN1BEI8MfJRR+HRKZY
+  mUtgzBwF1V4KIZQ8EuL6I/nHVu07i6IkrpAgxpXUfdJQJi0oZAqXurAV3yTxkFwd
+  g62YrrW26mDe+pZBzR6bpLE+PmXCzz7UxUq3AE0gPHbiMXie3EFE0oxnsU3lIduh
+  sCANiQ8BAgMBAAGjOTA3MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQW
+  BBS5k4Z75VSpdM0AclG2UvzFA/VW5DANBgkqhkiG9w0BAQUFAAOCAQEAHagT4lfX
+  kP/hDaiwGct7XPuVGbrOsKRVD59FF5kETBxEc9UQ1clKWngf8JoVuEoKD774dW19
+  bU0GOVWO+J6FMmT/Cp7nuFJ79egMf/gy4gfUfQMuvfcr6DvZUPIs9P/TlK59iMYF
+  DIOQ3DxdF3rMzztNUCizN4taVscEsjCcgW6WkUJnGdqlu3OHWpQxZBJkBTjPCoc6
+  UW6on70SFPmAy/5Cq0OJNGEWBfgD9q7rrs/X8GGwUWqXb85RXnUVi/P8Up75E0ag
+  14jEc90kN+C7oI/AGCBN0j6JnEtYIEJZibjjDJTSMWlUKKkj30kq7hlUC2CepJ4v
+  x52qPcexcYZR7w==
+  -----END CERTIFICATE-----
+
+date: 2010-04-19 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rdoc
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 5
+        version: "2.5"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rubyforge
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 0
+        - 3
+        version: 2.0.3
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: gemcutter
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 5
+        - 0
+        version: 0.5.0
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 5
+        - 0
+        version: 2.5.0
+  type: :development
+  version_requirements: *id004
+description: RDoc plugin for documenting rake tasks
+email: 
+- drbrain@segment7.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+files: 
+- .autotest
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- lib/rdoc/discover.rb
+- lib/rdoc/parser/rake.rb
+- test/test_rdoc_parser_rake.rb
+has_rdoc: true
+homepage: http://rdoc.rubyforge.org/rdoc-rake
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: rdoc
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: RDoc plugin for documenting rake tasks
+test_files: 
+- test/test_rdoc_parser_rake.rb

metadata.gz.sig

@@ -0,0 +1 @@
+J_nF���A�f�Y��B���<V��&���&�]�8�� ِղ���}���?�0f�l�a� ��9�7񬴃.a��9��W��W��[��
X�{�Ϛ��+��M�