tdoc 0.10.0 → 0.11.0

data/README.rdoc

@@ -1,40 +1,49 @@
 
 =Tdoc 
 
-== Test oriented documentation
+*WARNING*:  As of version 0.11.0 Tdoc contains an rdoc/discover file which parses .rdoc files by default.  I am not aware of any issues that this causes but I haven't tested it with any complex rdoc.  So, for now, if your rdoc executable is behaving in an unexpected way, remove this gem and try it again.  If it works, please file a bug report.  If it doesn't, then it's not my fault :).
 
-*note:* Version 0.4.0 completely breaks the API from 0.3.0
+== Test oriented documentation
 
 Tdoc takes a single argument specifying the file or glob to be processed.  If no arguments are given, Tdoc will process "README.rdoc" in the working directory.
 
 - Tdoc will map each file given to a Test::Unit::TestCase.
 - For each such file, named e.g. '_filename_.rdoc', Tdoc will:
-  - require '<i>filename</i>_include.rb' if it exists
-  - create a context with the test case for each file in the directory named '_filename_' if it exists.
+  - require '<i>filename</i>.rb' if it exists
+  - create a context within the test case for each file in the directory named '_filename_' if it exists.
   - process all :include: directives as follows:
-    - 
+    - If the included file has a .rb extention, it will be required in the context of the test case
+    - If it has a .rdoc extention it will map to a context within the test case
     
- 
-  
-- Tdoc directives take up 1 line, with the exception of the "examples" directive.  They may be preceded by any number of whitespace characters and terminate with a colon.
-- Tdoc understands the following directives:
-  - tdoc_require
-  - tdoc_context
-    - RDoc's standard :include: directive now does the same thing as tdoc_context
-  - tdoc_setup
-  - examples
-- within each examples block, Tdoc will convert cut and pastes from irb into assert_equal blocks, so
-    >> "asdf"
-    => "asdf"
-  turns into:
-    assert_equal "asdf","asdf"
+- In addition to ':include:', Tdoc understands the following directives:
+  - example(s): - Text between these directives maps to a Shoulda #should block 
+    - within each examples block, Tdoc will convert cut and pastes from irb into assert_equal blocks, so
+        >> "asdf"
+        => "asdf"
+      turns into:
+        assert_equal "asdf","asdf"
   Tdoc will then include all assertions within the context created from the example block
+  - setup/end - The first setup/end block is passed to the context's setup method
 
 usage:
 
-  tdoc [FILE_GLOB]
+  tdoc [file_glob]
+
+setup
+  @foo='bar'
+end
+
+The text between the horizontal lines is included with the ':include:' directive from rdoc/example.rdoc:
+
+----
+
+:include:rdoc/example.rdoc
+
+----
 
-examples:
+==Now we are back in the README.rdoc file.
 
-  :include:rdoc/example.rdoc
+example:
+    >>FOOBAR
+    =>'foobar'
 

data/bin/tdoc.rb

@@ -27,6 +27,7 @@ end
 def mk_test_context(file, test_case=nil)
   test_name=File.basename(file).sub(/\..*?$/,'')
   test_dir=File.dirname(file)
+  $: << test_dir unless $:.include?(test_dir)
   text=File.read(file)
   opts={
     :requires => Dir.glob("#{test_dir}/#{test_name}#{EXTENSIONS[:requires]}"),
@@ -46,7 +47,7 @@ def mk_test_context(file, test_case=nil)
   tests=text.split(/#{LINST}[Ee]xamples?:/).to_a[1..-1].to_a.map do |test|
     test.gsub!(/#{LINST}>>\s*(.+)\n#{LINST}=>\s*(.+)/) {|m| 
       expected, actual=[$2,$1]
-      #assert equal cannot take a hash as its first argument
+      #assert_equal cannot take a hash as its first argument
       expected.sub!(/^\{(.*)\}\s*$/) {|m| "Hash[#{$1}]"}
       "assert_equal #{expected}, #{actual}"
     }

data/lib/rdoc/discover

@@ -0,0 +1,2 @@
+  require 'rdoc/rdoc'
+  require 'rdoc/parsers/tdoc'

data/lib/rdoc/parsers/tdoc.rb

@@ -0,0 +1,27 @@
+class RDoc::Parser::Tdoc < RDoc::Parser::Simple
+  LINST='^[#|\s]*'
+  LINSTM='[#|\s]*'
+  parse_files_matching(/\.rdoc/)
+  def initialize(top_level, file_name, content, options, stats)
+    super
+    @content=process_includes(file_name)
+  end
+  def process_includes(file_name)
+    content=File.read(file_name)
+    test_name=File.basename(file_name,'.rdoc')
+    test_dir=File.dirname(file_name)
+    content.gsub!(/(#{LINST}):include:\s*(.+)/) {|foo| indent=$1;process_includes($2).sub(/^/,indent)}
+    content.sub!(/(#{LINST})setup\s+(.*?)#{LINSTM}end\s+/m) {|foo| 
+      indent=$1
+      "The following code: \n#{$2.gsub(/^/,indent+'  ')}\nprecedes each of the following examples.\n\n"
+    }
+    Dir.glob("#{test_dir}/#{test_name}.rb").each do |fn|
+      tests=content.split(/#{LINST}[Ee]xamples?:/,2)
+      content="#{tests[0]}\nThe following examples require the file '#{fn}', whose contents follow:\n#{process_includes(fn).gsub(/^/,'  ')}\nExamples: #{tests[1]}"
+    end
+    Dir.glob("#{test_dir}/#{test_name}/*.rdoc").each do |fn|
+      content+="\n#{process_includes(fn)}\n"
+    end
+    content
+  end
+end

data/rdoc/example.rb

@@ -0,0 +1,3 @@
+
+   #this text is inside example.rb and is included in example.rdoc by default
+   FOOBAR='foobar'

data/rdoc/example.rdoc

@@ -1,6 +1,12 @@
 
+==example.rdoc
+
+This text is in rdoc/example.rdoc
+
   examples: simple irb  with 1 assertion
     
+    >> FOOBAR
+    => 'foobar'
     >> "asdf"
     => "asdf"
     >> x="foo"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: tdoc
 version: !ruby/object:Gem::Version 
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors: 
 - Herb Daily
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-11-29 00:00:00 -03:00
+date: 2011-11-30 00:00:00 -03:00
 default_executable: tdoc.rb
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -33,7 +33,10 @@ extra_rdoc_files: []
 files: 
 - README.rdoc
 - bin/tdoc.rb
+- rdoc/example.rb
 - rdoc/example.rdoc
+- lib/rdoc/parsers/tdoc.rb
+- lib/rdoc/discover
 has_rdoc: true
 homepage: http://github.com/herbdaily/tdoc
 licenses: []