docubot 0.3 → 0.3.2

data/lib/docubot/bundle.rb

@@ -1,7 +1,8 @@
 # encoding: UTF-8
+require 'pathname'
 class DocuBot::Bundle
 	attr_reader :toc, :extras, :glossary, :index, :source
-	
+	attr_reader :internal_links, :external_links, :file_links, :broken_links
 	def initialize( source_directory )
 		@source = File.expand_path( source_directory )
 		raise "DocuBot cannot find directory #{@source}. Exiting." unless File.exists?( @source )
@@ -9,8 +10,7 @@ class DocuBot::Bundle
 		@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 = DocuBot::Page.new( self, ".", "Table of Contents" )
 			@toc.meta['glossary'] = @glossary
 			@toc.meta['index']    = @index
 			pages_by_path = { '.'=>@toc }
@@ -23,12 +23,11 @@ class DocuBot::Bundle
 				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
+					page = DocuBot::Page.new( self, item )
 					pages_by_path[ item ] = page
 					parent << page if parent
 					if item =~ /\b_glossary\b/
-						@glossary << page 
+						@glossary << page
 					end
 					@index.process_page( page )
 					
@@ -56,15 +55,80 @@ class DocuBot::Bundle
 				end
 			end
 		end
+		
+		# Regenerate pages whose templates require full scaning to have completed
+		# TODO: make this based off of a metasection attribute.
+		@toc.every_page.select do |page|
+			%w[ glossary ].include?( page.template )
+		end.each do |page|
+			page.dirty_template
+		end
+		
+		# TODO: make this optional via global variable
+		validate_links
+		@broken_links.each do |page,links|
+			links.each do |link|
+				warn "Broken link on #{page.file}: '#{link}'"
+			end
+		end
+		
+		# TODO: make this optional via global variable
+		@glossary.missing_terms.each do |term,referrers|
+			warn "Glossary term '#{term}' never defined."
+			referrers.each do |referring_page|
+				warn "...seen on #{referring_page.file}."
+			end
+		end
+		
 	end
-	
-	def write( writer_type, destination=nil)
+
+	def validate_links
+		@external_links = Hash.new{ |h,k| h[k]=[] }
+		@internal_links = Hash.new{ |h,k| h[k]=[] }
+		@file_links     = Hash.new{ |h,k| h[k]=[] }
+		@broken_links   = Hash.new{ |h,k| h[k]=[] }
+
+		page_by_html_path = {}
+		page_by_orig_path = {}
+		@toc.every_page.each do |page|
+			page_by_html_path[page.html_path] = page
+			page_by_orig_path[page.file]      = page if page.file
+		end
+
+		Dir.chdir( @source ) do 
+			@toc.every_page.each do |page|
+				next unless page.nokodoc # Sub-links don't have documents
+				page.nokodoc.xpath('//a/@href').each do |href|
+					href=href.content
+					if href=~%r{^[a-z]+://}i
+						@external_links[page] << href
+					else
+						id   = href[/(#[a-z][\w.:-]*)/i,1]
+						file = href.sub(/#.+/,'')
+						path = file.empty? ? page.html_path : Pathname.new( File.dirname(page.html_path) / file ).cleanpath.to_s
+						if target=page_by_html_path[path]
+							if !id || target.nokodoc.at_css(id)
+								@internal_links[page] << href
+							else
+								@broken_links[page] << href
+							end
+						else
+							if File.file?(path) && !page_by_orig_path[path]
+								@file_links[page] << href
+							else
+								@broken_links[page] << href
+							end
+						end
+					end
+				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

data/lib/docubot/glossary.rb

@@ -1,17 +1,16 @@
 # encoding: UTF-8
 class DocuBot::Glossary
-	attr_accessor :bundle
+	attr_accessor :bundle, :entries
 	def initialize( bundle, dir )
 		@entries   = {}
 		@downcased = {}
 		@bundle    = bundle
-		@missing   = []
+		@missing   = Hash.new{ |h,k| h[k]=[] }
 		# .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
+			# 	page = DocuBot::Page.new( @bundle, item )
 			# 	self << page
 			# end
 		end
@@ -19,26 +18,32 @@ class DocuBot::Glossary
 	def []=( term, definition )
 		@entries[ term ] = definition
 		@downcased[ term.downcase ] = term
+		@missing.delete( term.downcase )
 	end
 	def []( term )
 		@entries[ @downcased[ term.downcase ] ]
 	end
-	def each
-		@entries.each{ |term,defn| yield term, defn }
+	def term_used( term, referring_page )
+		down = term.downcase
+		unless @downcased[down]
+			@missing[down] << referring_page
+			@missing[down].uniq!
+		end
 	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
+	def each
+		@entries.each{ |term,page| yield term, page }
 	end
 	def missing_terms
-		# Terms may have been defined after being first seen
-		@missing.reject{ |term| self[term] }.uniq
+		@missing
 	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
+		self[ page.title ] = page
 	end
 	def to_js
-		"$glossaryTerms = {#{@entries.map{ |term,defn| "'#{term.downcase.gsub("'","\\\\'")}':'#{defn.gsub("'","\\\\'").gsub(/[\r\n]/,'\\n')}'" }.join(",\n")}};"
+		"$glossaryTerms = {#{
+			@entries.reject{ |term,page| page.hide }.map do |term,page|
+				"'#{term.downcase.gsub("'","\\\\'")}':'#{page.to_html.gsub("'","\\\\'").gsub(/[\r\n]/,'\\n')}'"
+			end.join(",\n")
+		}};"
 	end
 end

data/lib/docubot/page.rb

@@ -6,40 +6,96 @@ class DocuBot::Page
 	META_SEPARATOR = /^\+\+\+\s*$/ # Sort of like +++ATH0
 	AUTO_ID_ELEMENTS = %w[ h1 h2 h3 h4 h5 h6 legend caption dt ].join(',')
 
-	attr_reader :pages, :type, :folder, :file, :meta
-	attr_accessor :parent, :bundle
+	attr_reader :pages, :type, :folder, :file, :meta, :nokodoc, :bundle
+	attr_accessor :parent
 
-	def initialize( source_path, title=nil, type=nil )
+	def initialize( bundle, source_path, title=nil )
 		puts "#{self.class}.new( #{source_path.inspect}, #{title.inspect}, #{type.inspect} )" if $DEBUG
 		title ||= File.basename( source_path ).sub( /\.[^.]+$/, '' ).gsub( '_', ' ' ).sub( /^\d+\s/, '' )
+		@bundle = bundle
 		@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]
+			# Directories without an index.* file now have nil @file
 		else
 			@folder = File.dirname( @file )
 		end
+		slurp_file_contents if @file
+		create_nokodoc
+	end
+	
+	def slurp_file_contents
+		@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, needs content
+		if @raw = parts.last && parts.last.strip
+			@raw = nil if @raw.empty?
+		end
+	end
+	
+	def create_nokodoc
+		# Directories with no index.* file will not have any @raw
+		# Pages with metasection only will also not have any @raw
+		html = if @raw && !@raw.empty?
+			html = DocuBot::process_snippets( self, @raw )
+			html = DocuBot::convert_to_html( self, html, @type )
+		end
+		@nokodoc = Nokogiri::HTML(html || "")
+		auto_id
+		auto_section
+		@nokodoc
+	end
+	
+	def nokodoc
+		@nokodoc ||= create_nokodoc
+	end
 
-		# 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 )
+	# Add IDs to elements that don't have them
+	def auto_id
+		# ...but only if a toc entry might reference one, or requested.
+		if (@meta['auto-id']==true) || (@meta['toc'] && @meta['toc'][','])
+			@nokodoc.css( AUTO_ID_ELEMENTS ).each do |node|
+				next if node.has_attribute?('id')
+				node['id'] = DocuBot.id_from_text(node.inner_text)
 			end
-			
-			# Raw markup, untransformed
-			if @raw = parts.last && parts.last.strip
-				@raw = @raw
+			dirty_doc
+		end
+	end
+	
+	# Wrap siblings of headers in <div class='section'>
+	def auto_section
+		return if @meta['auto-section']==false
+		return unless body = @nokodoc.at_css('body')
+		
+		#TODO: Make this a generic nokogiri call on any node (like body) where you can pass in a hierarchy of elements and a wrapper
+		stack = []
+		body.children.each do |node|
+			# non-matching nodes will get level of 0
+			level = node.name[ /h([1-6])/i, 1 ].to_i
+			level = 99 if level == 0
+
+			stack.pop while (top=stack.last) && top[:level]>=level
+			stack.last[:div].add_child( node ) if stack.last
+			if level<99
+				div = Nokogiri::XML::Node.new('div',@nokodoc)
+				div.set_attribute( 'class', 'section' )
+				node.add_next_sibling(div)
+				stack << { :div=>div, :level=>level }
 			end
 		end
+		dirty_doc
 	end
+
 	def []( key )
 		@meta[key]
 	end
@@ -48,7 +104,6 @@ class DocuBot::Page
 		key=method.to_s
 		case key[-1..-1] # the last character of the method name
 			when '?' then @meta.has_key?( key[0..-2] )
-			#when '=' then @meta[ key[0..-2] ] = args[0]
 			when '!','=' then super
 			else @meta[ key ]
 		end
@@ -68,71 +123,75 @@ class DocuBot::Page
 	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
+		@_depth ||= self==@bundle.toc ? 0 : @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
+	
+	# Call this if the source generated by the converter would change
+	# THIS DESTROYS ANY CUSTOM CHANGES YOU HAVE MADE TO THE NOKODOC
+	def dirty_source
+		@nokodoc = nil
+	end
+	
+	# Call this after modifying the structure of the nokodoc for the page
+	def dirty_doc
+		@content_html = nil
+	end
 
-		contents = if @raw && !@raw.empty?
-			# Directories with no index.* file will not have any @raw
-			# TODO: Swap the order of these once we're sure that all converters will pass raw HTML through.
-			html = DocuBot::convert_to_html( self, @raw, @type )
-			DocuBot::process_snippets( self, html )
-		end
+	# Call this if the HTML generated by the page template needs to change
+	# e.g. for a glossary page.
+	def dirty_template
+		# to_html doesn't cache anything at this point
+		# so nothing needs to be done here
+	end
+	
+	def content_html
+		# Nokogiri 'helpfully' wraps our content in a full HTML page
+		# but apparently doesn't create a body for no content.
+		@content_html ||= (body=nokodoc.at_css('body')) && body.children.to_html
+	end
 
+	def to_html
+		#TODO: cache this is people keep calling to_html and it's a problem
 		@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 )
-		html = haml.render( Object.new, :contents=>contents, :page=>self, :global=>@bundle.toc, :root=>root )
-
-		# Add IDs to elements, only if a toc entry might reference one.
-		if @raw && @meta['toc'] && @meta['toc'][',']
-			nokodoc( html ).css( AUTO_ID_ELEMENTS ).each do |node|
-				next if node.has_attribute?('id')
-				node['id'] = DocuBot.id_from_text(node.inner_text)
-			end
-			html = @nokodoc.at_css('body').children.to_html
-		end		
-
-		@cached_html = html
-	end
-	def to_html!
-		@cached_html=nil
-		to_html
-	end
-	def nokodoc( html=nil )
-		@nokodoc ||= Nokogiri::HTML(html || to_html)
-	end
-	def nokodoc!
-		@nokodoc = Nokogiri::HTML(to_html!)
-	end
+		
+		tmpl = source_templates / "#{template}.haml"
+		tmpl = master_templates / "#{template}.haml" unless File.exists?( tmpl )
+		tmpl = master_templates / "page.haml"        unless File.exists?( tmpl )
+		haml = Haml::Engine.new( IO.read( tmpl ), DocuBot::Writer::HAML_OPTIONS )
+		haml.render( Object.new, :contents=>content_html, :page=>self, :global=>@bundle.toc, :root=>root )
+	end
+	
 end
 
 class DocuBot::SubLink
@@ -165,7 +224,6 @@ class DocuBot::SubLink
 	def ancestors
 		@page.ancestors
 	end
-	alias_method :to_html!, :to_html
 	def method_missing(*args)
 		nil
 	end

data/lib/docubot/shells/nvphysx/0_License.md

@@ -0,0 +1,3 @@
+style: license nosidebar
++++
+![NVIDIA 3D Badge](_static/NVBadge_3D.png)

data/lib/docubot/shells/nvphysx/1_Getting_Started.haml

@@ -0,0 +1,51 @@
+keywords: Basics
+toc     : welcome authoring glossary index
++++
+%h2#welcome Welcome to DocuBot for NVIDIA PhysX
+%p.sidebar
+	%img(width='150' src='_static/NVBadge_3D.png')
+	NVIDIA 3D Badge
+	%span#out
+:textile
+	This template shows the standard page style, which has a 350px sidebar on the right for including
+	images related to the text.
+	
+	To put images (with an optional description) in the sidebar, place them inside a paragraph with
+	the CSS class @sidebar@. They will float to the right next to your content.
+	
+	Each header will--by default--wait to begin until all images on the right have finished.
+
+%h2#authoring Authoring Content	
+<p class="sidebar"><img src="_static/PhysXbyNV_Black.png" width="180"></p>
+:markdown
+	The headers on each page should start at `h2` (not `h1`); `h1` is used for the title at the top of the page.
+	 
+	As shown in this template, if you apply HTML `id` attributes to the headers (or any other HTML element), and list those
+	identifiers under a toc entry at the top of the page, the Table of Contents will include sub-links to the headings.
+	
+%h2#glossary Glossary Entries
+%p
+	To create a reference to a glossary term, surround it in double dollar signs.
+	For example, $$NVIDIA$$ makes $$PhysX$$ and $$APEX Libraries:APEX$$.
+%p
+	As shown in the APEX link above, you can have the glossary text be different from the term it links to
+	by putting the words you want first, followed by a colon, followed by the actual glossary term to link to.
+%p
+	This works in all markups. (The processing happens after the markup is converted to HTML.)
+	
+%h2#index Managing the Index
+%p The index is automatically populated with the text from headings and defintions on the pages.
+%p To add additional terms, you can:
+%ul
+	%li
+		Use a <code>keywords</code> section at the top of the page with comma-delimited keywords or
+		phrases that you want the index to associate with the current page.
+	%li
+		:markdown
+			Put two `@` signs around any word or phrase in your text that you wanted added to the index.
+			
+			For example, imagine that this page talked about @@sexy code@@; the index now knows about that.
+			
+			Note that this syntax doesn't currently work with textile, because it uses single @ characters to
+			denote code. This will be fixed in the future (by processing glossary and index snippets before markup).
+