hanna 0.1.12

data/README.markdown

@@ -0,0 +1,102 @@
+# Hanna — a better RDoc template
+
+Hanna is an RDoc template that scales. It's implemented in Haml, making the sources clean
+and readable. It's built with simplicity, beauty and ease of browsing in mind. (See more
+in [the wiki][wiki].)
+
+Hanna gem is available from [Gemcutter][]:
+
+    gem install hanna
+
+The template was created by [Mislav][] and since then has seen contributions from:
+
+1. [Tony Strauss](http://github.com/DesigningPatterns), who participated from the early
+   start and made tons of fixes and enhancements to the template;
+2. [Hongli Lai](http://blog.phusion.nl/) with the search filter for methods.
+
+
+## Usage
+
+There is a command-line tool installed with the Hanna gem:
+
+    hanna -h
+
+This is a wrapper over `rdoc` and it forwards all the parameters to it. Manual usage
+would require specifying Hanna as a template when invoking RDoc on the command-line:
+
+    rdoc -o doc --inline-source --format=html -T hanna lib/*.rb
+    
+Hanna requires the `--inline-source` (or `-S`) flag.
+
+An alternative is to set the `RDOCOPT` environment variable:
+
+    RDOCOPT="-S -f html -T hanna"
+
+This will make RDoc always use Hanna unless it is explicitly overridden.
+
+Another neat trick is to put the following line in your .gemrc:
+
+    rdoc: --inline-source --line-numbers --format=html --template=hanna
+
+This will make RubyGems use Hanna when generating documentation for installed gems.
+
+### Rake task
+
+For repeated generation of API docs, it's better to set up a Rake task. If you already
+have an `RDocTask` set up in your Rakefile, the only thing you need to change is this:
+
+    # replace this:
+    require 'rake/rdoctask'
+    # with this:
+    require 'hanna/rdoctask'
+
+Tip: you can do this in the Rakefile of your Rails project before running `rake doc:rails`.
+
+Here is an example of a task for the [will_paginate library][wp]:
+
+    # instead of 'rake/rdoctask':
+    require 'hanna/rdoctask'
+    
+    desc 'Generate RDoc documentation for the will_paginate plugin.'
+    Rake::RDocTask.new(:rdoc) do |rdoc|
+      rdoc.rdoc_files.include('README.rdoc', 'LICENSE', 'CHANGELOG').
+        include('lib/**/*.rb').
+        exclude('lib/will_paginate/named_scope*').
+        exclude('lib/will_paginate/array.rb').
+        exclude('lib/will_paginate/version.rb')
+      
+      rdoc.main = "README.rdoc" # page to start on
+      rdoc.title = "will_paginate documentation"
+      
+      rdoc.rdoc_dir = 'doc' # rdoc output folder
+      rdoc.options << '--webcvs=http://github.com/mislav/will_paginate/tree/master/'
+    end
+
+### Generating documentation for installed gems
+
+You can generate documentation for installed gems, which might be more convenient than the
+`gem rdoc` command with the +RDOCOPT+ environment variable set as described. For instance,
+to generate docs for "actionpack" and "activerecord" type:
+
+    [sudo] hanna --gems actionpack activerecord
+
+
+## You can help
+
+Don't like something? Think you can design better? (You probably can.)
+
+I think of Hanna as the first RDoc template that's actually _maintainable_. First thing I
+have done is converted the original HTML template to Haml and Sass, cleaning up and
+removing the (ridiculous amount of) duplication. Also, the template fragments are now in
+_separate files_.
+
+Ultimately, I'd like to lose the frameset. Currently that is far from possible because the
+whole RDoc HTML Generator is built for frames. Still, that is my goal.
+
+This is git. Fork it, hack away, tell me about it!
+
+
+[wiki]: http://github.com/mislav/hanna/wikis/home "Hanna wiki"
+[gemcutter]: http://gemcutter.org/ "Gemcutter gem server"
+[wp]: http://github.com/mislav/will_paginate/tree/master/Rakefile
+[Mislav]: http://mislav.caboo.se/ "Mislav Marohnić"

data/Rakefile

@@ -0,0 +1,4 @@
+desc "builds the gem"
+task :gem do
+  system %(gem build hanna.gemspec)
+end

data/bin/hanna

@@ -0,0 +1,81 @@
+#!/usr/bin/ruby
+if ARGV.size == 1 and ARGV.first == '-h'
+  puts <<-HELP
+Hanna -- a better RDoc template
+Synopsis:
+  hanna [options]  [file names...]
+  [sudo] hanna --gems  [gem names...]
+  
+Example usage:
+
+  hanna lib/**/*.rb
+
+Hanna passes all arguments to RDoc. To find more about RDoc options, see
+"rdoc -h". Default options are:
+
+  -o doc --inline-source --charset=UTF-8
+
+The second form, with the "--gems" argument, serves the same purpose as
+the "gem rdoc" command: it generates documentation for installed gems.
+When no gem names are given, "hanna --gems" will install docs for EACH of
+the gems, which can, uh, take a little while.
+
+HELP
+  exit 0
+end
+
+unless RUBY_PLATFORM =~ /(:?mswin|mingw)/
+  require 'pathname'
+  hanna_dir = Pathname.new(__FILE__).realpath.dirname + '../lib'
+else
+  # windows
+  hanna_dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+end
+
+$:.unshift(hanna_dir) unless $:.include?(hanna_dir)
+
+require 'rubygems'
+require 'hanna/version'
+Hanna::require_rdoc
+require 'rdoc/rdoc'
+
+options = []
+
+options << '-f' << 'html' << '-T' << 'hanna'
+options << '--inline-source' << '--charset=UTF-8'
+
+if ARGV.first == '--gems'
+  require 'rubygems/doc_manager'
+  Gem::DocManager.configured_args = options
+  
+  gem_names = ARGV.dup
+  gem_names.shift
+  
+  unless gem_names.empty?
+    specs = gem_names.inject([]) do |arr, name|
+      found = Gem::SourceIndex.from_installed_gems.find_name(name)
+      spec = found.sort_by {|s| s.version }.last
+      arr << spec if spec
+      arr
+    end
+  else
+    specs = Gem::SourceIndex.from_installed_gems.inject({}) do |all, pair|
+      full_name, spec = pair
+      if spec.has_rdoc? and (!all[spec.name] or spec.version > all[spec.name].version)
+        all[spec.name] = spec
+      end
+      all
+    end
+    specs = specs.values
+    puts "Hanna is installing documentation for #{specs.size} gem#{specs.size > 1 ? 's' : ''} ..."
+  end
+
+  specs.each do |spec|
+    Gem::DocManager.new(spec).generate_rdoc
+  end
+else
+  options << '-o' << 'doc' unless ARGV.include?('-o') or ARGV.include?('--op')
+  options.concat ARGV
+
+  RDoc::RDoc.new.document(options)
+end

data/lib/hanna.rb

@@ -0,0 +1 @@
+require 'hanna/hanna'

data/lib/hanna/hanna.rb

@@ -0,0 +1,48 @@
+# = A better RDoc HTML template
+#
+# Authors: Mislav Marohnić <mislav.marohnic@gmail.com>
+#          Tony Strauss (http://github.com/DesigningPatterns)
+#          Michael Granger <ged@FaerieMUD.org>, who had maintained the original RDoc template
+
+require 'haml'
+require 'sass'
+require 'rdoc/generator/html'
+require 'hanna/template_page_patch'
+
+module RDoc::Generator::HTML::HANNA
+  class << self
+    def dir
+      @dir ||= File.join File.dirname(__FILE__), 'template_files'
+    end
+
+    def read(*names)
+      content = names.inject('') { |all, name| all << File.read(File.join(dir, name)) }
+      extension = names.first =~ /\.(\w+)$/ && $1
+
+      Hanna::TemplateHelpers.silence_warnings do
+        case extension
+        when 'sass'
+          Sass::Engine.new(content)
+        when 'haml'
+          Haml::Engine.new(content, :format => :html4, :filename => names.join(','))
+        else
+          content
+        end
+      end
+    end
+  end
+
+  STYLE = read('styles.sass')
+
+  CLASS_PAGE  = read('page.haml')
+  FILE_PAGE   = CLASS_PAGE
+  METHOD_LIST = read('method_list.haml', 'sections.haml')
+
+  FR_INDEX_BODY = BODY = read('layout.haml')
+
+  FILE_INDEX   = read('file_index.haml')
+  CLASS_INDEX  = read('class_index.haml')
+  METHOD_INDEX = read('method_index.haml')
+
+  INDEX = read('index.haml')
+end 

data/lib/hanna/rdoctask.rb

@@ -0,0 +1,42 @@
+require 'hanna/version'
+require 'rake'
+require 'rake/rdoctask'
+
+Rake::RDocTask.class_eval do
+  # don't allow it
+  undef :external=, :template=
+  
+  # Create the tasks defined by this task lib.
+  def define
+    @template = 'hanna'
+    options << '--format=html'
+    
+    # inline source and UTF-8 are defaults:
+    options << '--inline-source' unless options.include? '--inline-source' or options.include? '-S'
+    options << '--charset=UTF-8' if options.grep(/^(--charset\b|-c\b)/).empty?
+    
+    desc "Build the HTML documentation"
+    task name
+    
+    desc "Force a rebuild of the RDOC files"
+    task paste("re", name) => [paste("clobber_", name), name]
+
+    desc "Remove rdoc products" 
+    task paste("clobber_", name) do
+      rm_r rdoc_dir rescue nil
+    end
+
+    task :clobber => [paste("clobber_", name)]
+      
+    directory @rdoc_dir
+    task name => [rdoc_target]
+    file rdoc_target => @rdoc_files + [Rake.application.rakefile] do
+      rm_r @rdoc_dir rescue nil
+      Hanna::require_rdoc
+      require 'rdoc/rdoc'
+      
+      RDoc::RDoc.new.document(option_list + @rdoc_files)
+    end
+    return self
+  end
+end

data/lib/hanna/template_files/class_index.haml

@@ -0,0 +1,3 @@
+%h1= values[:list_title]
+%ol#index-entries.classes
+  = render_class_tree make_class_tree(values[:entries])

data/lib/hanna/template_files/file_index.haml

@@ -0,0 +1,12 @@
+%h1= values[:list_title]
+- any_hidden = false
+
+%ol#index-entries{ :class => 'files' }
+  - for entry in values[:entries]
+    - hide = entry[:name] =~ /\.rb$/
+    - any_hidden = true if hide
+    %li{ :class => hide ? 'other' : nil }= link_to entry[:name], entry[:href]
+
+  - if any_hidden
+    %li
+      %a.show{ :href => '#', :onclick => 'this.parentNode.parentNode.className += " expanded"; this.parentNode.removeChild(this); return false' } show all

data/lib/hanna/template_files/index.haml

@@ -0,0 +1,11 @@
+!!! Frameset
+%html{ "xml:lang" => "en", :lang => "en", :xmlns => "http://www.w3.org/1999/xhtml" }
+  %head
+    %title= values[:title]
+    %meta{ :content => "text/html; charset=#{values[:charset]}", "http-equiv" => "Content-Type" }
+  %frameset{ :cols => "20%, *", :border => "1", :frameborder => "1", :bordercolor => "gray" }
+    %frameset{ :rows => "15%, 35%, 50%" }
+      %frame{ :name => "Files", :title => "Files", :src => "fr_file_index.html" }
+      %frame{ :name => "Classes", :src => "fr_class_index.html" }
+      %frame{ :name => "Methods", :src => "fr_method_index.html" }
+    %frame{ :name => "docwin", :src => values[:initial_page] }=""

data/lib/hanna/template_files/layout.haml

@@ -0,0 +1,34 @@
+!!! strict
+- index = values[:list_title]
+%html{ :lang => "en" }
+  %head
+    %title= values[:title]
+    %meta{ 'http-equiv' => "Content-Type", :content => "text/html; charset=#{values[:charset]}" }
+    %link{ :rel => "stylesheet", :href => values[:style_url], :type => "text/css", :media => "screen" }
+    - unless index
+      :javascript
+        function popupCode(url) {
+          window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
+        }
+
+        function toggleCode(id) {
+          var code = document.getElementById(id)
+
+          code.style.display = code.style.display != 'block' ? 'block' : 'none'
+          return true
+        }
+
+        // Make codeblocks hidden by default
+        document.writeln('<' + 'style type="text/css">.method .source pre { display: none }<\/style>')
+    - else
+      %base{ :target => 'docwin' }/
+        
+  %body{ :class => index ? 'list' : 'page' }
+    - if index
+      #index= yield
+    - else
+      #wrapper{ :class => values[:classmod] ? 'class' : 'file' }
+        = yield
+        #footer-push
+      #footer
+        = link_to '<strong>Hanna</strong> RDoc template', 'http://github.com/mislav/hanna/tree/master'

data/lib/hanna/template_files/method_index.haml

@@ -0,0 +1,13 @@
+%h1= values[:list_title]
+
+%script{:type => 'text/javascript'}
+  = read("prototype-1.6.0.3.js")
+  = build_javascript_search_index(values[:entries])
+  = read("method_search.js")
+%form{:onsubmit => 'return performSearch()'}
+  %input{:type => 'text', :id => 'search', :class => 'untouched', :value => 'Enter search terms...'}
+%ol#search-results{ :class => 'methods', :style => 'display: none' }
+
+%ol#index-entries{ :class => 'methods' }
+  - for entry in values[:entries]
+    %li= link_to_method entry[:name], entry[:href]

data/lib/hanna/template_files/method_list.haml

@@ -0,0 +1,37 @@
+- methods = methods_from_sections values[:sections]
+- unless methods.empty?
+  #method-list
+    %h2 Methods
+    - for type in ['public class', 'protected class', 'public instance', 'protected instance']
+      - unless (list = methods[type]).empty?
+        %h3= type
+        %ol
+          - for method in list
+            - if method[:name].to_s.empty? && method[:callseq]
+              %li= link_to method[:callseq].gsub(/<br\s*\/?>/, "").split(/[\r\n]+/).map{ |s| s.split(/([({]+|\[\{|\s+(#?=>|&rarr;)\s+)/).first.sub(/^[A-Za-z0-9_:]+\./, "").sub(/\s+=\s+.*/, "=").strip }.uniq.join("<br />\n"), '#' + method[:aref]
+            - else
+              %li= link_to method[:name], '#' + method[:aref]
+
+- if values[:requires] or values[:toc] or values[:includes]
+  #context
+    - if values[:requires]
+      #requires
+        %h2 Required files
+        %ol
+          - for req in values[:requires]
+            %li= link_to req[:name], req[:aref]
+            
+    - if values[:toc]
+      #contents
+        %h2 Contents
+        %ol
+          - for item in values[:toc]
+            %li= link_to values[:secname], values[:href]
+
+    - if values[:includes]
+      #includes
+        %h2 Included modules
+        %ol
+          - for inc in values[:includes]
+            %li= link_to inc[:name], inc[:aref]
+

data/lib/hanna/template_files/method_search.js

@@ -0,0 +1,63 @@
+$(document).observe('dom:loaded', function() {
+	// Setup search-during-typing.
+	new Form.Element.Observer('search', 0.3, function(element, value) {
+		performSearch();
+	});
+	
+	// Remove the default search box value when the user puts the focus on
+	// the search box for the first time.
+	var search_box = $('search');
+	if ($F('search') == 'Enter search terms...') {
+		search_box.observe('focus', function() {
+			if (search_box.hasClassName('untouched')) {
+				search_box.removeClassName('untouched');
+				search_box.value = '';
+			}
+		});
+	} else {
+		search_box.removeClassName('untouched');
+	}
+	
+	search_box.insert({
+	  after: new Element('span', { 'class': 'clear_button' }).update('x').observe('click', function(e) {
+	    e.stopPropagation()
+  	  search_box.setValue('')
+  	  search_box.focus()
+  	})
+  })
+});
+
+function searchInIndex(query) {
+	var i;
+	var results = [];
+	query = query.toLowerCase();
+	for (i = 0; i < search_index.length; i++) {
+		if (search_index[i].method.indexOf(query) != -1) {
+			results.push(search_index[i]);
+		}
+	}
+	return results;
+}
+
+function buildHtmlForResults(results) {
+	var html = "";
+	var i;
+	for (i = 0; i < results.length; i++) {
+		html += '<li>' + results[i].html + '</li>';
+	}
+	return html;
+}
+
+function performSearch() {
+	var query = $F('search');
+	if (query == '') {
+		$('index-entries').show();
+		$('search-results').hide();
+	} else {
+		var results = searchInIndex(query);
+		$('search-results').update(buildHtmlForResults(results));
+		$('index-entries').hide();
+		$('search-results').show();
+	}
+	return false;
+}