ddollar-hanna 0.1.4

data/Manifest

@@ -0,0 +1,20 @@
+bin/hanna
+lib/hanna/hanna.rb
+lib/hanna/rdoc_version.rb
+lib/hanna/rdoctask.rb
+lib/hanna/template_files/class_index.haml
+lib/hanna/template_files/file_index.haml
+lib/hanna/template_files/index.haml
+lib/hanna/template_files/layout.haml
+lib/hanna/template_files/method_list.haml
+lib/hanna/template_files/method_search.js
+lib/hanna/template_files/page.haml
+lib/hanna/template_files/prototype-1.6.0.3.js
+lib/hanna/template_files/sections.haml
+lib/hanna/template_files/styles.sass
+lib/hanna/template_helpers.rb
+lib/hanna/template_page_patch.rb
+lib/hanna.rb
+Rakefile
+README.markdown
+Manifest

data/README.markdown

@@ -0,0 +1,106 @@
+# 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 was made by [Mislav][] and is available from [GitHub][]:
+
+    gem install mislav-hanna
+
+
+## Usage
+
+After installing, you have several options.
+---
+Hanna can be used as a normal RDoc template by specifying
+  -S -T hanna
+to rdoc.  Note that Hanna requires the -S option, which inlines source
+code.
+---
+You can use the command-line tool included in the Hanna gem:
+
+    hanna -h
+
+This is a wrapper over the rdoc script that makes RDoc use the Hanna
+template.
+---
+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
+    
+Alternatively, you can use the the standard RDocTask and simply set the
+task's +template+ attribute to +hanna+ and append +--inline-source+ to its
+options attribute.
+
+A third alternative is to set the +RDOCOPT+ environment variable to
+
+    -T hanna -S
+
+which will make RDoc always use Hanna unless this is overridden on the
+command-line.
+--
+You also can generate documentation for installed gems, which might be more
+convenient than the
+
+  gem rdoc
+
+command (with the +RDOCOPT+ environment variable set as above).  For this, do:
+
+    [sudo] hanna --gems haml will_paginate
+
+## A work in progress
+
+Hanna is far from done, but it is 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_. You would have
+fainted if you seen how it was before. (It's really no wonder why there are no
+other RDoc templates around ... save one: [Allison][].)
+
+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.
+
+## You can help
+
+Don't like something? Think you can design better? (You probably can.)
+
+This is git. I welcome all submissions towards my goal.
+
+
+[wiki]: http://github.com/mislav/hanna/wikis/home "Hanna wiki"
+[GitHub]: http://gems.github.com/ "GitHub gem source"
+[wp]: http://github.com/mislav/will_paginate
+[Mislav]: http://mislav.caboo.se/ "Mislav Marohnić"
+[Allison]: http://blog.evanweaver.com/files/doc/fauna/allison/ "A modern, pretty RDoc template"

data/Rakefile

@@ -0,0 +1,24 @@
+#
+# This can be made cleaner by using the relative gem.
+#
+require File.join(File.dirname(__FILE__), "lib/hanna/rdoc_version")
+
+require 'echoe'
+
+Echoe.new('hanna') do |p|
+  p.version = '0.1.4'
+  
+  p.summary = "An RDoc template that rocks"
+  p.description = "Hanna is an RDoc template that scales. It's implemented in Haml, making its source clean and maintainable. It's built with simplicity, beauty and ease of browsing in mind."
+  
+  p.author = 'Mislav Marohnić'
+  p.email  = 'mislav.marohnic@gmail.com'
+  p.url    = 'http://github.com/mislav/hanna'
+  
+  p.executable_pattern = ['bin/hanna']
+  p.has_rdoc = false
+  p.runtime_dependencies = []
+  p.runtime_dependencies << ['rdoc', Hanna::RDOC_VERSION_REQUIREMENT]
+  p.runtime_dependencies << ['haml', '~> 2.0']
+  p.runtime_dependencies << ['rake', '~> 0.8.2']
+end

data/bin/hanna

@@ -0,0 +1,75 @@
+#!/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
+
+require 'rubygems'
+
+hanna_dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+$:.unshift(hanna_dir) unless $:.include?(hanna_dir)
+
+require 'hanna/rdoc_version'
+Hanna::require_rdoc
+require 'rdoc/rdoc'
+
+options = []
+
+options << '-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/hanna.gemspec

@@ -0,0 +1,44 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{hanna}
+  s.version = "0.1.4"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Mislav Marohni\304\207"]
+  s.date = %q{2008-11-18}
+  s.default_executable = %q{hanna}
+  s.description = %q{Hanna is an RDoc template that scales. It's implemented in Haml, making its source clean and maintainable. It's built with simplicity, beauty and ease of browsing in mind.}
+  s.email = %q{mislav.marohnic@gmail.com}
+  s.executables = ["hanna"]
+  s.extra_rdoc_files = ["bin/hanna", "lib/hanna/hanna.rb", "lib/hanna/rdoc_version.rb", "lib/hanna/rdoctask.rb", "lib/hanna/template_files/class_index.haml", "lib/hanna/template_files/file_index.haml", "lib/hanna/template_files/index.haml", "lib/hanna/template_files/layout.haml", "lib/hanna/template_files/method_list.haml", "lib/hanna/template_files/method_search.js", "lib/hanna/template_files/page.haml", "lib/hanna/template_files/prototype-1.6.0.3.js", "lib/hanna/template_files/sections.haml", "lib/hanna/template_files/styles.sass", "lib/hanna/template_helpers.rb", "lib/hanna/template_page_patch.rb", "lib/hanna.rb", "README.markdown"]
+  s.files = ["bin/hanna", "lib/hanna/hanna.rb", "lib/hanna/rdoc_version.rb", "lib/hanna/rdoctask.rb", "lib/hanna/template_files/class_index.haml", "lib/hanna/template_files/file_index.haml", "lib/hanna/template_files/index.haml", "lib/hanna/template_files/layout.haml", "lib/hanna/template_files/method_list.haml", "lib/hanna/template_files/method_search.js", "lib/hanna/template_files/page.haml", "lib/hanna/template_files/prototype-1.6.0.3.js", "lib/hanna/template_files/sections.haml", "lib/hanna/template_files/styles.sass", "lib/hanna/template_helpers.rb", "lib/hanna/template_page_patch.rb", "lib/hanna.rb", "Rakefile", "README.markdown", "Manifest", "hanna.gemspec"]
+  s.homepage = %q{http://github.com/mislav/hanna}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Hanna", "--main", "README.markdown"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{hanna}
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{An RDoc template that rocks}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rdoc>, ["~> 2.2.0"])
+      s.add_runtime_dependency(%q<haml>, ["~> 2.0"])
+      s.add_runtime_dependency(%q<rake>, ["~> 0.8.2"])
+      s.add_development_dependency(%q<echoe>, [">= 0"])
+    else
+      s.add_dependency(%q<rdoc>, ["~> 2.2.0"])
+      s.add_dependency(%q<haml>, ["~> 2.0"])
+      s.add_dependency(%q<rake>, ["~> 0.8.2"])
+      s.add_dependency(%q<echoe>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rdoc>, ["~> 2.2.0"])
+    s.add_dependency(%q<haml>, ["~> 2.0"])
+    s.add_dependency(%q<rake>, ["~> 0.8.2"])
+    s.add_dependency(%q<echoe>, [">= 0"])
+  end
+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)
+        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 = FILE_INDEX
+
+  INDEX = read('index.haml')
+end 

data/lib/hanna/rdoc_version.rb

@@ -0,0 +1,21 @@
+module Hanna
+  #
+  # The version of RDoc that Hanna should use.
+  #
+  RDOC_VERSION = '2.2.0'
+  RDOC_VERSION_REQUIREMENT = "~> #{RDOC_VERSION}"
+
+  #
+  # This method loads the correct version of RDoc.  If the correct
+  # version of RDoc is not present, this method will terminate the
+  # program with a helpful error message.
+  #
+  def self.require_rdoc
+    begin
+      gem 'rdoc', RDOC_VERSION_REQUIREMENT
+    rescue Gem::LoadError
+      $stderr.puts "Error: hanna requires the RDoc #{RDOC_VERSION} gem!"
+      exit 1
+    end 
+  end
+end

data/lib/hanna/rdoctask.rb

@@ -0,0 +1,41 @@
+require 'hanna/rdoc_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'
+    
+    # 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,25 @@
+%h1= values["list_title"]
+- type = values["list_title"].downcase
+- any_hidden = false
+
+- if type == 'methods'
+  %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 => type, :style => 'display: none' }
+
+%ol#index-entries{ :class => type }
+  - for entry in values["entries"]
+    - hide = type == 'files' && entry['name'] =~ /\.rb$/
+    - any_hidden = true if hide
+    - if type == 'methods'
+      %li{ :class => hide ? 'other' : nil }= link_to_method entry['name'], entry['href']
+    - else
+      %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%, *" }
+    %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,38 @@
+!!! 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'
+        hand-crafted by
+        %strong= link_to 'Mislav', 'http://mislav.caboo.se/'
+        and
+        %strong= link_to 'Hongli', 'http://blog.phusion.nl/'