docubot 0.3 → 0.3.2

data/lib/docubot/templates/glossary.haml

@@ -1,5 +1,6 @@
 -# TODO: Breakdown by letter.
 %dl#glossary
-	- global.glossary.each do |term,defn|
+	- global.glossary.each do |term,page|
+		- next if page.hide
 		%dt= term
-		%dd= defn
+		%dd= page.to_html

data/lib/docubot/templates/top.haml

@@ -3,6 +3,9 @@
 	%head
 		%meta(http-equiv='Content-Type' content='text/html; charset=utf-8')
 		%link{:rel=>'stylesheet', :type=>'text/css', :href=>"#{root}common.css", :media=>'all'}
+		%link{:rel=>'stylesheet', :type=>'text/css', :href=>"#{root}glossary.css", :media=>'all'}
+		%script{:type=>'text/javascript', :src=>"#{root}glossary-terms.js"}
+		%script{:type=>'text/javascript', :src=>"#{root}glossary.js"}
 		%title= page.title
 	%body{ :class=>page.style }
 		#content
@@ -19,6 +22,7 @@
 				- if page.author?
 					#author= page.author
 			#pagebody
+				#glossary-box
 				#mainbody= contents
 				#pagefooter
 					Copyright ©#{Time.now.year}#{ " #{global.company}" if global.company? }.

data/lib/docubot/writers/chm.rb

@@ -14,7 +14,8 @@ class DocuBot::CHMWriter < DocuBot::HTMLWriter
 		write_hhc
 		write_hhk
 		write_hhp
-		puts "...%.2fs to write the CHM support files" % ((lap=Time.now)-lap)
+		puts "...%.2fs to write the CHM support files" % (Time.now-lap)
+		lap = Time.now
 		
 		# This will fail if a handle is open to it on Windows
 		begin
@@ -26,12 +27,14 @@ class DocuBot::CHMWriter < DocuBot::HTMLWriter
 			end
 		end
 		`hhc.exe "#{FileUtils.win_path @hhp}"`.gsub( /[\r\n]+/, "\n" )
-		puts "...%.2fs to create the CHM" % ((lap=Time.now)-lap)
+		puts "...%.2fs to create the CHM" % (Time.now-lap)
+		lap = Time.now
 		
 		# Clean out the intermediary files
 		FileUtils.rm( [ @hhc, @hhp, @hhk ] )
 		FileUtils.rm_r( @html_path )
-		puts "...%.2fs to clean up temporary files" % ((lap=Time.now)-lap)
+		puts "...%.2fs to clean up temporary files" % (Time.now-lap)
+		lap = Time.now
 		
 		# Spin a new thread so it doesn't hold up the Ruby process, but sleep long enough for it to get going.
 		Thread.new{ `hh.exe "#{FileUtils.win_path @chm_path}"` }

data/lib/docubot/writers/html.rb

@@ -37,7 +37,7 @@ class DocuBot::HTMLWriter < DocuBot::Writer
 			template = Haml::Engine.new( IO.read( template ), HAML_OPTIONS )
 			@bundle.toc.descendants.each do |page|
 				next if page.sublink?
-				contents = page.to_html!
+				contents = page.to_html
 				root = "../" * page.depth
 				html = template.render( o, :page=>page, :contents=>contents, :global=>@bundle.toc, :root=>root )
 				FileUtils.mkdir_p( File.dirname( page.html_path ) )

data/spec/_all.rb

@@ -0,0 +1,12 @@
+#encoding: UTF-8
+$: << '..'
+require 'spec/bundle'
+require 'spec/toc'
+require 'spec/converters'
+require 'spec/page'
+require 'spec/glossary'
+require 'spec/index'
+require 'spec/templates'
+require 'spec/command'
+require 'spec/writer/html'
+require 'spec/writer/chm'

data/spec/_helper.rb

@@ -0,0 +1,6 @@
+$: << File.join( File.dirname(__FILE__), '..' )
+$: << File.join( File.dirname(__FILE__), '..', 'lib' )
+require 'minitest/spec'
+require 'docubot'
+SAMPLES = File.dirname(__FILE__)/'samples'
+MiniTest::Unit.autorun

data/spec/bundle.rb

@@ -0,0 +1,142 @@
+#encoding: UTF-8
+require File.join(File.dirname(__FILE__), "_helper")
+
+describe "AbusedBundle" do
+	it 'requires a valid path' do
+		proc{ DocuBot::Bundle.new }.must_raise(ArgumentError)
+		proc{ DocuBot::Bundle.new "does not exist" }.must_raise(RuntimeError)
+		DocuBot::Bundle.new(SAMPLES/'empty').wont_be_nil
+	end
+end
+
+describe "Bundle from empty directory" do
+	before do
+		@out, @err = capture_io do
+			@bundle = DocuBot::Bundle.new SAMPLES/'empty'
+		end
+	end
+	
+	it "should have an empty TOC" do
+		@bundle.toc.wont_be_nil
+		@bundle.toc.pages.must_be_empty
+	end
+	
+	it "should have an empty index" do
+	  @bundle.index.wont_be_nil
+		@bundle.index.entries.must_be_empty
+	end
+
+	it "should have an empty glossary" do
+	  @bundle.glossary.wont_be_nil
+		@bundle.glossary.entries.must_be_empty
+	end
+	
+	it "should have an empty external link list" do
+		@bundle.external_links.wont_be_nil
+		@bundle.external_links.must_be_empty
+	end
+	
+	it "should have an empty internal link list" do
+		@bundle.internal_links.wont_be_nil
+		@bundle.internal_links.must_be_empty
+	end
+	
+	it "should have an empty file link list" do
+		@bundle.file_links.wont_be_nil
+		@bundle.file_links.must_be_empty
+	end
+	
+	it "should have an empty broken link list" do
+		@bundle.broken_links.wont_be_nil
+		@bundle.broken_links.must_be_empty
+	end
+	
+	it "should produce no warnings" do
+		@err.must_be_empty
+	end
+	
+end
+
+
+describe "Gathering links" do
+	before do
+		@out, @err = capture_io do
+			@bundle = DocuBot::Bundle.new SAMPLES/'link_test'
+		end
+	end
+	
+	it "should have link collections be pages hashed to arrays of strings" do
+		%w[ external_links internal_links file_links broken_links ].each do |method|
+			collection = @bundle.send(method)
+			collection.must_be_kind_of Hash
+			collection.keys.each do |key|
+				key.must_be_kind_of DocuBot::Page
+			end
+			collection.values.each do |value|
+				value.must_be_kind_of Array
+				value.each do |item|
+					item.must_be_kind_of String
+				end
+			end
+		end
+	end
+	
+	it "should identify (but not validate) external links" do
+		known_external = %w[ http://www.google.com/ http://phrogz.net http://phrogz.net/tmp/gkhead.jpg HTTP://NONEXISTENT.SITE ]
+		all_external = @bundle.external_links.values.flatten
+		known_external.each do |link|
+			all_external.must_include link
+		end
+	end
+	
+	it "should identify and warn about broken internal links" do
+		known_broken = %w[
+			fork.html sub1.html root.md sub1/inner1.md
+			inner2.html ../sub1 sub1/inner1.md
+			../index.html ../sub1 ../index.md
+			sub2/GORKBO.bin
+		]
+		all_broken = @bundle.broken_links.values.flatten
+		known_broken.each do |link|
+			all_broken.must_include link
+			@err.must_include link
+		end		
+	end
+	
+	it "should identify valid links to pages or sections" do
+		known_internal = %w[
+			sub1/inner1.html sub2.html sub2/inner2.html sub1/../sub2/inner2.html
+			../root.html inner1.html ../sub2.html ../sub2/inner2.html
+			../sub1/index.html index.html
+		]
+		all_internal = @bundle.internal_links.values.flatten
+		known_internal.each do |link|
+			all_internal.must_include link
+		end		
+	end
+	
+	it "should identify valid links to internal files" do
+		known_file_links = %w[ ../sub2/bozo.bin bozo.bin sub2/bozo.bin ]
+		all_file_links = @bundle.file_links.values.flatten
+		known_file_links.each do |link|
+			all_file_links.must_include link
+		end		
+	end
+	
+	it "should identify and warn about invalid sub-page anchors" do
+		known_broken = %w[ #GORKBO ../root.html#GORKBO ]
+		all_broken = @bundle.broken_links.values.flatten
+		known_broken.each do |link|
+			all_broken.must_include link
+			@err.must_include link
+		end		
+	end
+
+	it "should identify valid sub-page anchors" do
+		known_internal = %w[ #sub-id root.html#sub-id ../root.html#sub-id ]
+		all_internal = @bundle.internal_links.values.flatten
+		known_internal.each do |link|
+			all_internal.must_include link
+		end		
+	end
+end

data/spec/command.rb

@@ -0,0 +1,3 @@
+#encoding: UTF-8
+require File.join(File.dirname(__FILE__), "_helper")
+

data/spec/converters.rb

@@ -0,0 +1,2 @@
+#encoding: UTF-8
+require File.join(File.dirname(__FILE__), "_helper")

data/spec/glossary.rb

@@ -0,0 +1,93 @@
+#encoding: UTF-8
+require File.join(File.dirname(__FILE__), "_helper")
+
+describe "Glossary Scanner" do
+	before do
+		@public_terms = [ "Simple Term", "Complex Term" ]
+		@hidden_terms = [ "Secret Term"]
+		@all_terms = @public_terms + @hidden_terms
+		@expected_paragraphs = {
+			"Simple Term"  => 2,
+			"Complex Term" => 3
+		}
+		@out, @err = capture_io do
+			@bundle   = DocuBot::Bundle.new SAMPLES/'glossary'
+			@glossary = @bundle.glossary
+			@page     = @bundle.toc.every_page.find{ |page| page.title=='Glossary' }
+			@fulldoc  = Nokogiri::HTML( @page.to_html )
+		end
+	end
+	
+	# No _glossary folder handled in the Bundle spec for empty site
+	
+	it "should have one internal entry for each term defined in _glossary" do
+		@glossary.entries.size.must_equal @all_terms.length
+	end
+
+	it "should honor page titles as terms" do
+		@all_terms.each do |term|
+			@glossary.entries[term].wont_be_nil
+		end
+	end
+	
+	it "uses DocuBot::Page instances for the definitions" do
+		@glossary.entries.values.each do |defn|
+			defn.must_be_kind_of DocuBot::Page
+		end
+		@glossary.entries["Secret Term"].hide.must_equal true
+	end
+
+	it "supports iterating over the entries with each" do
+		count = 0
+		@glossary.each do |page,defn|
+			page.must_be_kind_of String
+			defn.must_be_kind_of DocuBot::Page
+			count += 1
+		end
+		count.must_equal @all_terms.length
+	end
+	
+	
+	it "uses converters for page content" do
+		@expected_paragraphs.each do |term,paras|
+			@glossary.entries[term].nokodoc.xpath('//p').length.must_equal paras
+		end
+	end
+	
+	it "supports a glossary template that generates HTML for terms" do
+		definitions = @fulldoc.xpath('//dt')
+		@expected_paragraphs.each do |term,paras|
+			dt = definitions.find{ |node| node.inner_text==term }
+			dt.wont_be_nil
+			dt.next_element.xpath('.//p').length.must_equal paras			
+		end
+	end
+
+	it "does not include hidden pages in the output" do
+		definitions = @fulldoc.xpath('//dt')
+		@hidden_terms.each do |term|
+			@fulldoc.at_xpath("//dt[text()='#{term}']").must_be_nil
+		end
+	end
+end
+
+describe "Glossary Snippet" do
+	before do
+		@out, @err = capture_io do
+			@bundle   = DocuBot::Bundle.new SAMPLES/'glossary'
+			@glossary = @bundle.glossary
+		end
+	end
+	
+	it "should know about missing terms" do
+		@glossary.missing_terms.must_include "crazy term"
+	end
+	
+	it "should not mistake alternate text for a missing term" do
+		@glossary.missing_terms.wont_include "more complex term"
+	end
+	
+	it "should warn about missing terms" do
+		@err.must_include "crazy term"
+	end
+end

data/spec/index.rb

@@ -0,0 +1,2 @@
+#encoding: UTF-8
+require File.join(File.dirname(__FILE__), "_helper")

data/spec/page.rb

@@ -0,0 +1,24 @@
+#encoding: UTF-8
+require File.join(File.dirname(__FILE__), "_helper")
+
+describe "Pages from 'titletest'" do
+	before do
+		@bundle = DocuBot::Bundle.new( SAMPLES/'titletest' )
+		@toc    = @bundle.toc
+	end
+	it "knows who its bundle is" do
+		@toc.pages.each{ |page| page.bundle.must_equal @bundle }
+	end
+	it "ignores leading numbers for the titles" do
+		@toc.pages.each{ |page| page.title.must_match /^\D/ }
+	end
+	it "honors pages specifying their title" do
+		@toc.pages.find{ |page| page.title =~ /renamed/i  }.must_be_nil
+		@toc.pages.find{ |page| page.title == 'Third One' }.wont_be_nil
+	end
+	it "replaces underscores with spaces in the title" do
+		%w[ First Second Third Fourth Fifth ].each_with_index do |name,i|
+			@toc.pages[i].title.must_equal "#{name} One"
+		end
+	end
+end

data/spec/samples/glossary/Glossary.txt

@@ -0,0 +1,5 @@
+template: glossary
++++
+The `glossary.haml` template writes out the glossary contents.
+This page tells it where to be generated and how to be named.
+The contents of this page are ignored by the `glossary.haml` template.

data/spec/samples/glossary/Some Page.md

@@ -0,0 +1,3 @@
+This page mentions both a $$simple term$$ and a $$more complex term:complex term$$.
+
+It also mentions a $$crazy term$$, which is never defined.

data/spec/samples/glossary/_glossary/Simple Term.md

@@ -0,0 +1,3 @@
+This is a simple term.
+
+It is defined in two paragraphs.

data/spec/samples/glossary/_glossary/complex.haml

@@ -0,0 +1,8 @@
+title: Complex Term
+todo : Document why this is complex.
++++
+- 3.times do |i|
+	%p
+		This is a complex term.
+		It is described in three paragraphs.
+		This is paragraph ##{i+1}.

data/spec/samples/glossary/_glossary/project_x.md

@@ -0,0 +1,4 @@
+title: Secret Term
+hide : true
++++
+This must not be shown until the aliens have revealed themselves to the public.

data/spec/samples/link_test/index.txt

@@ -0,0 +1,11 @@
+The global root of the site is not a valid link.
+
+                 | external | valid | file | broken |
+-----------------+----------+-------+------+--------+
+| root.md        |    1     |   6   |   0  |    5   |
+| sub1/inner1.md |    1     |   5   |   1  |    4   |
+| sub2/inner2.md |    1     |   2   |   1  |    3   |
+| sub2.md        |    1     |   0   |   1  |    1   |
+-----------------+----------+-------+------+--------+
+          TOTALS |    4     |   13  |   3  |   13   |
+                 +----------+-------+------+--------+

data/spec/samples/link_test/root.md

@@ -0,0 +1,14 @@
+[External](http://www.google.com/)
+[Internal](#sub-id)
+[Internal](root.html#sub-id)
+[Internal](sub1/inner1.html)
+[Internal](sub2.html)
+[Internal](sub2/inner2.html)
+[Internal](sub1/../sub2/inner2.html)
+[BROKEN](fork.html)
+[BROKEN](sub1.html)
+[BROKEN](root.md)
+[BROKEN](sub1/inner1.md)
+[BROKEN](#GORKBO)
+
+<div id="sub-id">Just in case</div>

data/spec/samples/link_test/sub1/inner1.md

@@ -0,0 +1,11 @@
+[External](http://phrogz.net)
+[Internal](../root.html)
+[Internal](../root.html#sub-id)
+[Internal](inner1.html)
+[Internal](../sub2.html)
+[Internal](../sub2/inner2.html)
+[File](../sub2/bozo.bin)           
+[BROKEN](inner2.html)
+[BROKEN](../sub1)
+[BROKEN](sub1/inner1.md)
+[BROKEN](../root.html#GORKBO)

data/spec/samples/link_test/sub2.md

@@ -0,0 +1,3 @@
+[External](HTTP://NONEXISTENT.SITE)
+[File](sub2/bozo.bin)           
+[BROKEN](sub2/GORKBO.bin)           

data/spec/samples/link_test/sub2/inner2.md

@@ -0,0 +1,7 @@
+[External](http://phrogz.net/tmp/gkhead.jpg)
+[Internal](../sub1/index.html) Even though there isn't an index.md file.
+[Internal](index.html)         Even though there isn't an index.md file.
+[File](bozo.bin)           
+[BROKEN](../index.html)    Because the global root is not a valid link.
+[BROKEN](../sub1)
+[BROKEN](../index.md)