docubot 0.0.1 → 0.2

data/bin/docubot

@@ -1,36 +1,105 @@
-#!/usr/bin/env ruby
+#!/usr/bin/env ruby -KU
+# encoding: UTF-8
+
+# Hack to allow the binary to be run without the gem installed
+$: << File.join( File.dirname( __FILE__ ), '..', 'lib' )
 
 require 'rubygems'
 require 'docubot'
 
 USAGE = <<ENDUSAGE
 Usage:
-   docubot [-t template_name] directory
+   docubot [-h] [create [-s shell] [-f]] directory [-w writer] [-o output_file]
 ENDUSAGE
 
-ARGS = { :template=>'default' }
+HELP = <<ENDHELP
+   -h, --help    Show this help.
+   create        Create a starter directory filled with example files;
+                 also copies the template for easy modification, if desired.
+   -s, --shell   The shell to copy from.
+                 Available shells: #{DocuBot::SHELLS.join(', ')}
+   -f, --force   Force create over an existing directory,
+                 deleting any existing files.
+   -w, --writer  The output type to create [Defaults to 'chm']
+                 Available writers: #{DocuBot::Writer::INSTALLED_WRITERS.join(', ')}
+   -o, --output  The file or folder (depending on the writer) to create.
+                 [Default value depends on the writer chosen.]
+
+ENDHELP
+
+ARGS = { :shell=>'default', :writer=>'chm' }
 UNFLAGGED_ARGS = [ :directory ]
 next_arg = UNFLAGGED_ARGS.first
 ARGV.each{ |arg|
 	case arg
 		when '-h','--help'
 		  ARGS[:help] = true
-		when '-t','--template'
-			next_arg = :template
+		when 'create'
+		  ARGS[:create] = true
+		when '-f','--force'
+		  ARGS[:force] = true
+		when '-s','--shell'
+			next_arg = :shell
+		when '-w','--writer'
+			next_arg = :writer
+		when '-o','--output'
+			next_arg = :output
 		else
-		  if next_arg
-		    ARGS[next_arg] = arg
-		    UNFLAGGED_ARGS.delete( next_arg )
-		  end
-		  next_arg = UNFLAGGED_ARGS.first
+			if next_arg
+				ARGS[next_arg] = arg
+				UNFLAGGED_ARGS.delete( next_arg )
+			end
+			next_arg = UNFLAGGED_ARGS.first
 	end
 }
 
 if ARGS[:help] or !ARGS[:directory]
-   puts USAGE
-   #puts EXAMPLES if ARGS[:help]
-   exit
+	puts USAGE
+	puts HELP if ARGS[:help]
+	exit
 end
 
-DocuBot.generate( ARGS[:directory], ARGS )
+if ARGS[:create]
+	require 'fileutils'
+
+	unless DocuBot::SHELLS.include?( ARGS[:shell] )
+		puts "  Error: '#{ARGS[:shell]}' is not a valid shell.",
+		     "  Available shells: #{DocuBot::SHELLS.join(', ')}",
+		     "  (Shells are installed in #{DocuBot::DIR/'shells'})", ""
+		exit 1
+	end
+
+	if File.exist?( ARGS[:directory] )
+		if ARGS[:force]
+			# TODO: confirmation?
+			# TODO: May be able to just use :force=>true for cp_r
+			FileUtils.rm_rf( ARGS[:directory] )
+		else
+			puts "  Error: directory '#{ARGS[:directory]}' already exists.",
+			     "  Use the --force option to forcibly overwrite.", ""
+			exit 1
+		end
+	end
+
+	dest = File.expand_path( ARGS[:directory] )
+	src  = File.expand_path( DocuBot::SHELL_DIR/ARGS[:shell] )
+	puts "  Creating:   #{dest}",
+	     "  as copy of: #{src}", ""	
+	
+	# Copy template files first so that the shell can overwrite if it wants
+	FileUtils.mkdir_p( dest )
+	FileUtils.cp_r( DocuBot::TEMPLATE_DIR, dest/'_templates' )
+	
+	Dir.chdir src do
+		Dir['**/*.*'].each do |file|
+			dest_file = dest/file
+			dest_dir  = File.dirname(dest_file)
+			FileUtils.mkdir_p( dest_dir )
+			FileUtils.cp( file, dest_file )
+		end
+	end
+else
+	bundle = DocuBot::Bundle.new( ARGS[:directory] )
+	bundle.write( ARGS[:writer], ARGS[:output] )
+end
 

data/lib/docubot.rb

@@ -1,14 +1,37 @@
-module DocuBot
-	VERSION = '0.0.1'
-	DIR     = File.dirname( __FILE__ )
-	def self.name( file_path )
-		no_extension = File.basename( file_path ).sub( /\.[^.]+$/, '' )
-		no_ordering  = no_extension.sub( /^\d*\s/, '' )
+# encoding: UTF-8
+# Assume all files read in are UTF-8 format
+if Object.const_defined? "Encoding"
+	Encoding.default_external = Encoding.default_internal = 'UTF-8'
+end
+
+# Wicked monkey patch to avoid File.join verbosity everywhere
+class String
+	def / ( other )
+		File.join( self, other )
+	end
+end
+
+require 'fileutils'
+
+module FileUtils
+	def self.win_path( path )
+		path.gsub( '/', '\\' )
 	end
 end
+
+module DocuBot
+	VERSION = '0.2'
+	DIR     = File.expand_path( File.dirname( __FILE__ ) )
+	
+	TEMPLATE_DIR = DIR / 'docubot/templates'
+	SHELL_DIR    = DIR / 'docubot/shells'
+	Dir.chdir( SHELL_DIR ){ SHELLS = Dir['*'] }
+end
+
+require 'docubot/snippet'
 require 'docubot/converter'
-require 'docubot/section'
+require 'docubot/writer'
 require 'docubot/page'
-require 'docubot/template'
-require 'docubot/snippet'
-require 'docubot/generator'
+require 'docubot/glossary'
+require 'docubot/index'
+require 'docubot/bundle'

data/lib/docubot/bundle.rb

@@ -0,0 +1,68 @@
+# encoding: UTF-8
+class DocuBot::Bundle
+	attr_reader :toc, :extras, :glossary, :index, :source
+	
+	def initialize( source_directory )
+		@source = File.expand_path( source_directory )
+		raise "DocuBot cannot find directory #{@source}. Exiting." unless File.exists?( @source )
+		@extras = []
+		@glossary = DocuBot::Glossary.new( self, @source/'_glossary' )
+		@index    = DocuBot::Index.new( self )
+		Dir.chdir( @source ) do
+			@toc = DocuBot::Page.new( ".", "Table of Contents" )
+			@toc.bundle = self
+			@toc.meta['glossary'] = @glossary
+			@toc.meta['index']    = @index
+			pages_by_path = { '.'=>@toc }
+		
+			files_and_folders = Dir[ '**/*' ]
+			files_and_folders.reject!{ |f| File.basename(f) =~ /^index\.[^.]+$/ || File.basename(f) == '_static' || File.basename(f) == '_glossary' }
+			files_and_folders.reject!{ |f| f =~ /\b_templates\b/ }
+			files_and_folders.each do |item|
+				extension = File.extname( item )[ 1..-1 ]
+				item_is_page = File.directory?(item) || DocuBot::Converter.by_type[extension]
+				if item_is_page
+					parent = pages_by_path[ File.dirname( item ) ]
+					page = DocuBot::Page.new( item )
+					page.bundle = self
+					pages_by_path[ item ] = page
+					parent << page if parent
+					if item =~ /\b_glossary\b/
+						@glossary << page 
+					end
+					@index.process_page( page )
+					
+					# TODO: Move this bloat elsewhere.
+					if page.toc?
+						html = page.to_html
+						page.toc.scan /[a-z][\w.:-]*/ do |id|
+							# TODO: Maybe a lightweight HTML parser would be faster here? (Certainly more robust.)
+							if title = html[/\bid *= *['"]#{id}['"][^>]*>([^<]+)/,1]
+								page << DocuBot::SubLink.new( page, title.strip, id )
+							else
+								warn "Could not find requested toc anchor '##{id}' on #{page.html_path}"
+							end
+						end
+					end
+					
+				else
+					# TODO: Anything better needed?
+					@extras << item
+				end
+			end
+		end
+	end
+	
+	def write( writer_type, destination=nil)
+		writer = DocuBot::Writer.by_type[ writer_type.to_s.downcase ]
+		if writer
+			writer.new( self ).write( destination )
+			unless @glossary.missing_terms.empty?
+				warn "The following glossary terms were never defined:\n#{@glossary.missing_terms.map{|t|t.inspect}.join(', ')}"
+			end			
+		else
+			raise "Unknown writer '#{writer_type}'; available types: #{DocuBot::Writer::INSTALLED_WRITERS.join ', '}"
+		end
+	end
+	
+end

data/lib/docubot/converter.rb

@@ -1,21 +1,25 @@
+# encoding: UTF-8
 module DocuBot
 	module Converter
-		@@by_type = {}
-		def converts_for( *types )
-			types.each{ |type| @@by_type[type.to_s] = self }
+		@by_type = {}
+		def self.to_convert( *types, &block )
+			types.each{ |type| @by_type[type.to_s] = block }
 		end
 		def self.by_type
-			@@by_type
+			@by_type
 		end
 	end
 
-	def self.convert_to_html( source, type )
-		converter = DocuBot::Converter.by_type[ type.to_s ]
-		raise "No converter found for type #{type}" unless converter
-		converter.new( source ).to_html
+	def self.convert_to_html( page, source, type )
+		if converter = DocuBot::Converter.by_type[ type.to_s ]
+			puts "Converting #{type}: #{source.inspect[0..60]}" if $DEBUG
+			converter[ page, source ]
+		else
+			raise "No converter found for type #{type}"
+		end
 	end
 end
 
-Dir[ File.join( DocuBot::DIR, 'docubot/converters/*.rb' ) ].each do |converter|
+Dir[ DocuBot::DIR/'docubot/converters/*.rb' ].each do |converter|
 	require converter
 end

data/lib/docubot/converters/haml.rb

@@ -0,0 +1,9 @@
+# encoding: UTF-8
+require 'rubygems'
+require 'haml'
+options = { :format=>:html4, :ugly=>true }
+options.merge!( :encoding=>'utf-8' ) if Object.const_defined? "Encoding"
+
+DocuBot::Converter.to_convert :haml do |page, source|
+	Haml::Engine.new( source, options ).render( page, :page=>page, :global=>page.bundle.toc, :root=>page.root )
+end

data/lib/docubot/converters/html.rb

@@ -0,0 +1,5 @@
+# encoding: UTF-8
+DocuBot::Converter.to_convert :html, :htm do |page, source_html|
+	# TODO: If the html is inside a body, strip out the surrounds.
+	source_html
+end

data/lib/docubot/converters/markdown.rb

@@ -1,6 +1,14 @@
+# encoding: UTF-8
 require 'rubygems'
-require 'bluecloth'
-class BlueCloth
-	extend DocuBot::Converter
-	converts_for :md, :markdown
+begin
+	require 'bluecloth'
+	DocuBot::Converter.to_convert :md, :markdown do |page, source|
+		# BlueCloth 2.0.5 takes UTF-8 source and returns ASCII-8BIT
+		result = BlueCloth.new(source).to_html
+		result.encode!( 'UTF-8', :undef=>:replace ) if Object.const_defined? "Encoding"
+		result		
+	end
+rescue LoadError
+	warn "Unable to load bluecloth gem; *.markdown/*.md markup will not be recognized as a page."
 end
+

data/lib/docubot/converters/raw_code.rb

@@ -0,0 +1,5 @@
+# encoding: UTF-8
+require 'cgi'
+DocuBot::Converter.to_convert :rb, :c, :h, :cpp, :cs, :txt, :raw do |page, source|
+	"<pre>#{CGI.escapeHTML source}</pre>"
+end

data/lib/docubot/converters/textile.rb

@@ -0,0 +1,10 @@
+# encoding: UTF-8
+require 'rubygems'
+begin
+	require 'redcloth'
+	DocuBot::Converter.to_convert :textile, :rc do |page, source|
+		RedCloth.new(source,[:no_span_caps]).to_html
+	end
+rescue LoadError
+	warn "Unable to load RedCloth gem; *.textile/*.rc markup will not be recognized as a page."
+end

data/lib/docubot/glossary.rb

@@ -0,0 +1,44 @@
+# encoding: UTF-8
+class DocuBot::Glossary
+	attr_accessor :bundle
+	def initialize( bundle, dir )
+		@entries   = {}
+		@downcased = {}
+		@bundle    = bundle
+		@missing   = []
+		# .directory? also ensures that the path exists
+		if File.directory?( dir )
+			@directory = File.expand_path( dir )
+			# Dir[ dir/'*' ].each do |item|
+			# 	page = DocuBot::Page.new( item )
+			# 	page.bundle = @bundle
+			# 	self << page
+			# end
+		end
+	end
+	def []=( term, definition )
+		@entries[ term ] = definition
+		@downcased[ term.downcase ] = term
+	end
+	def []( term )
+		@entries[ @downcased[ term.downcase ] ]
+	end
+	def each
+		@entries.each{ |term,defn| yield term, defn }
+	end
+	def add_missing_term( term )
+	  @missing << term.downcase
+		# File.open( @directory/"#{term}.md", "w" ){ |f| f << "<span class='todo'>TODO: define #{term}</span>" } if @directory
+	end
+	def missing_terms
+		# Terms may have been defined after being first seen
+		@missing.reject{ |term| self[term] }.uniq
+	end
+	def <<( page )
+		#TODO: perhaps don't serialize the page here, but wait until some #write call gives us a template so we can use that?
+		self[ page.title ] = page.to_html
+	end
+	def to_js
+		"$glossaryTerms = {#{@entries.map{ |term,defn| "'#{term.downcase.gsub("'","\\\\'")}':'#{defn.gsub("'","\\\\'").gsub(/[\r\n]/,'\\n')}'" }.join(",\n")}};"
+	end
+end

data/lib/docubot/index.rb

@@ -0,0 +1,66 @@
+# encoding: UTF-8
+
+# The index links keywords to a particular page.
+#
+# Keywords are added to the index by:
+#  * Having a "keywords" entry in the metasection, e.g.
+#    keywords: Rigid Bodies, Dynamic, Physical Mesh
+#  * Surrounding a word or phrase on the page with two @ characters, e.g.
+#    The purpose of a @@physical mesh@@ is to...
+#  * Having an "index: headings" entry in the metasection, causing each
+#    heading on the page to be added to the index.
+#  * Having an "index: definitions" entry in the metasection, causing each
+#    <dt>...</dt> on the page to be added to the index.
+#    (May be combined with the above as "index: headings definitions".)
+#
+# As shown above, terms may be referenced in title or lowercase.
+# Names with capital letters will be favored over lowercase in the index.
+class DocuBot::Index
+	attr_reader :entries
+	def initialize( bundle )
+		@bundle    = bundle
+		@entries   = Hash.new{|h,k|h[k]=[]} # key points to array of DocuBot::Pages
+		@downcased = {}
+		#TODO: support links to sub-sections instead of just pages
+	end
+	
+	# Run through the 'keywords' and 'index' meta attribute for a page and add entries
+	# Note: in-content @@keyword@@ marks are processed by snippets/index_entries.rb 
+	def process_page( page )
+		page.keywords.split(/,\s*/).each{ |key| add( key, page ) } if page.keywords?
+
+		html = page.to_html
+		unless page['no-index'] && page['no-index'].include?( 'headings' )
+			#TODO: Fix the regex to use a backreference to ensure the correct closing tag, once 1.8x support is not necessary
+			html.scan( %r{<h[1-6][^>]*>(.+?)</h[1-6]>}im ){ |captures| add( captures.first, page ) }
+		end
+
+		unless page['no-index'] && page['no-index'].include?( 'definitions' )
+			html.scan( %r{<dt[^>]*>(.+?)</dt>}im ){ |captures| add captures.first, page }
+		end
+	end
+	
+	def add( term, page )
+		term.strip!
+		term.gsub!(/<[^>]+>/,'')
+		down = term.downcase
+		if existing = @downcased[ down ]
+			# The existing entry might be early-arriving all-lowercase.
+			# If the new term has more capital letters, it wins.
+			if term.scan(/[A-Z]/).length > existing.scan(/[A-Z]/).length
+				@downcased[ down ] = term
+				@entries[ term ] = @entries[ existing ]
+				@entries.delete( existing )
+			else
+				term = existing
+			end
+		end
+		@entries[ term ] << page
+		@entries[ term ].uniq!
+		@downcased[ down ] = term
+	end
+	
+	def each
+		@entries.each{ |term, pages| yield term, pages }
+	end
+end

data/lib/docubot/page.rb

@@ -1,33 +1,157 @@
+# encoding: UTF-8
 require 'yaml'
 class DocuBot::Page
-	META_SEPARATOR = /^\+\+\+$/ # Sort of like +++ATH0
+	META_SEPARATOR = /^\+\+\+\s*$/ # Sort of like +++ATH0
 
-	attr_reader :html
+	attr_reader :pages, :type, :folder, :file, :meta
+	attr_accessor :parent, :bundle
 
-	def self.from_file( filename, title=nil, type=:md )
-		title ||= DocuBot.name( filename )
-		type  ||= File.extname( filename )[ 1..-1 ]
-		new( File.read(filename), title, type )
-	end
+	def initialize( source_path, title=nil, type=nil )
+		puts "#{self.class}.new( #{source_path.inspect}, #{title.inspect}, #{type.inspect} )" if $DEBUG
+		title ||= File.basename( source_path ).sub( /\.[^.]+$/, '' ).gsub( '_', ' ' ).sub( /^\d+\s/, '' )
+		@meta  = { 'title'=>title }
+		@pages = []
+		@file  = source_path
+		if File.directory?( @file )
+			@folder = @file
+			# WILL SET @file TO NIL FOR DIRECTORIES WITHOUT AN INDEX.* FILE
+			@file   = Dir[ source_path/'index.*' ][0]
+		else
+			@folder = File.dirname( @file )
+		end
 
-	def initialize( source, title=nil, type=:md )
-		parts = source.split( META_SEPARATOR, 2 )
-		@meta = { 'title'=>title }
-		@meta.merge!( YAML.load( parts.first ) ) if parts.length > 1
-		@html = DocuBot::convert_to_html( parts.last, type )
-		@html = DocuBot::process_snippets( @html )
+		# Directories without an index file have no @file
+		if @file
+			@type = type || File.extname( @file )[ 1..-1 ]
+			parts = IO.read( @file ).split( META_SEPARATOR, 2 )
+			
+			if parts.length > 1
+				# Make YAML friendler to n00bs
+				yaml = YAML.load( parts.first.gsub( /^\t/, '  ' ) )
+				@meta.merge!( yaml )
+			end
+			
+			# Raw markup, untransformed
+			@raw = parts.last
+		end
+	end
+	def []( key )
+		@meta[key]
 	end
 
 	def method_missing( method, *args )
 		key=method.to_s
-		case key[-1..-1]
+		case key[-1..-1] # the last character of the method name
 			when '?' then @meta.has_key?( key[0..-2] )
-			when '!', '=' then super
+			#when '=' then @meta[ key[0..-2] ] = args[0]
+			when '!','=' then super
 			else @meta[ key ]
 		end
 	end
-	
-	def to_s( depth=0 )
-		"#{'  '*depth}#{@meta['title']}"
+	def ancestors
+		page = self
+		anc = []
+		anc.unshift( page ) while page = page.parent
+		anc
+	end	
+	def sections
+		@pages.reject{ |e| e.pages.empty? }
+	end
+	def leafs
+		@pages.select{ |e| e.pages.empty? }
+	end
+	def every_leaf
+		(leafs + sub_sections.map{ |sub| sub.every_leaf }).flatten
+	end
+	def every_section
+		(sub_sections + sub_sections.map{ |sub| sub.every_section }).flatten
+	end
+	def descendants
+		(@pages + @pages.map{ |page| page.descendants }).flatten
+	end
+	alias_method :every_page, :descendants
+	def <<( entry )
+		@pages << entry
+		entry.parent = self
+	end
+	def leaf?
+		@pages.empty? || @pages.all?{ |x| x.is_a?(DocuBot::SubLink) }
+	end
+	def depth
+		@_depth ||= @file ? @file.count('/') : @folder.count('/') + 1
+	end
+	def root
+		@_root ||= "../" * depth
+	end
+	def html_path
+		@file ? @file.sub( /[^.]+$/, 'html' ) : ( @folder / 'index.html' )
+	end
+	def to_html
+		return @cached_html if @cached_html
+
+		contents = if @raw
+			# Directories with no index.* file will not have any @raw
+			html = DocuBot::convert_to_html( self, @raw, @type )
+			DocuBot::process_snippets( self, html )
+		end
+
+		@meta['template'] ||= leaf? ? 'page' : 'section'
+
+		master_templates = DocuBot::TEMPLATE_DIR
+		source_templates = @bundle.source / '_templates'
+
+		haml = source_templates / "#{template}.haml"
+		haml = master_templates / "#{template}.haml" unless File.exists?( haml )
+		haml = master_templates / "page.haml"        unless File.exists?( haml )
+		haml = Haml::Engine.new( IO.read( haml ), DocuBot::Writer::HAML_OPTIONS )
+		contents = haml.render( Object.new, :contents=>contents, :page=>self, :global=>@bundle.toc, :root=>root )
+
+		@cached_html = contents
+	end
+	def to_html!
+		@cached_html=nil
+		to_html
+	end
+end
+
+class DocuBot::SubLink
+	attr_reader :page, :title, :id
+	def initialize( page, title, id )
+		@page, @title, @id = page, title, id
+	end
+	def html_path
+		"#{@page.html_path}##{@id}"
+	end
+	def leaf?
+		true
+	end
+	def pages
+		[]
+	end
+	alias_method :descendants, :pages
+	def depth
+		@page.depth
+	end
+	def parent
+		@page
+	end
+	def parent=( page )
+		@page = page
+	end
+	def to_html
+		""
+	end
+	def ancestors
+		@page.ancestors
+	end
+	alias_method :to_html!, :to_html
+	def method_missing(*args)
+		nil
+	end
+	def hide
+		false
+	end
+	def sublink?
+		true
 	end
 end