hanna-nouveau 0.2.0

data/Gemfile

@@ -0,0 +1,12 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.1"
+  gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,18 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.8.7)
+    rcov (0.9.9)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.5.1)
+  rcov

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2009 Mislav Marohnić
+Copyright (c) 2010, 2011 Erik Hollensbe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of 
+this software and associated documentation files (the "Software"), to deal in 
+the Software without restriction, including without limitation the rights to 
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 
+the Software, and to permit persons to whom the Software is furnished to do so, 
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all 
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,108 @@
+= Hanna Nouveau — a better RDoc template, now for RDoc 2.5 and 3.0.
+
+Based on the original Hanna by Mislav.
+
+Hanna is an RDoc generator 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}[http://github.com/mislav/hanna/wikis/home].)
+
+Hanna gem is available from http://rubygems.org:
+
+    gem install hanna
+
+The template was created by {Mislav}[http://mislav.caboo.se/] 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.
+3. {Erik Hollensbe}[http://github.com/erikh] a serious refactoring and up to
+   date with RDoc 2.5.x.
+4. {James Tucker}[http://github.com/raggi] minor cleanups for Erik.
+
+== Usage
+
+    rdoc -o doc -f hanna lib/*.rb
+
+An alternative is to set the `RDOCOPT` environment variable:
+
+    RDOCOPT="-f hanna"
+
+This will make RDoc always use Hanna unless it is explicitly overridden.
+
+== Integrating with RubyGems
+
+Another neat trick is to put the following line in your .gemrc, this will make
+RubyGems use Hanna for all rdoc generation:
+
+    rdoc: -f 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. Simply
+add the hanna format argument to your RDoc::Task options:
+
+    require 'hanna'
+    require 'rdoc/task'
+    RDoc::Task.new do |rdoc|
+      rdoc.options.push '-f', 'hanna'
+    end
+
+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 {rdbi
+library}[http://github.com/rdbi/rdbi/tree/master/Rakefile]:
+
+    require 'hanna'
+    require 'rdoc/task'
+    RDoc::Task.new do |rdoc|
+      version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+      rdoc.options.push '-f', 'hanna'
+      rdoc.main = 'README.rdoc'
+      rdoc.rdoc_dir = 'rdoc'
+      rdoc.title = "RDBI #{version} Documentation"
+      rdoc.rdoc_files.include('README*')
+      rdoc.rdoc_files.include('lib/**/*.rb')
+    end
+
+== Generating documentation for installed gems
+
+The gem comes with a RubyGems plugin that overrides the gem default arguments
+to RDoc to use Hanna.
+
+To regenerate documentation for a specific gem, first configure RubyGems to
+use Hanna, by adding the following to your .gemrc:
+
+    rdoc: -f  hanna
+
+Now to regenerate documentation for an already installed gem:
+
+    gem rdoc mygem --overwrite
+
+To regenerate documentation for all gems:
+
+    gem rdoc --all --overwrite
+
+To easily browse your newly created documentation, use `gem server`.
+
+== 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!
+

data/Rakefile

@@ -0,0 +1,55 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "hanna-nouveau"
+  gem.homepage = "http://github.com/erikh/hanna-nouveau"
+  gem.license = "MIT"
+  gem.summary = %Q{A rework of the Hanna generator for RDoc 2.5 and 3.0}
+  gem.description = %Q{}
+  gem.email = "erik@hollensbe.org"
+  gem.authors = ["Erik Hollensbe"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  gem.add_runtime_dependency 'haml'
+  gem.add_runtime_dependency 'rdoc'
+  gem.add_development_dependency 'jeweler'
+  gem.add_development_dependency 'rake'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "hanna-nouveau #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/hanna.gemspec

@@ -0,0 +1,21 @@
+Gem::Specification.new do |gem|
+  gem.name    = 'hanna'
+  gem.version = eval(File.read('lib/hanna.rb')[/^\s+VERSION\s+=\s+(.*)$/, 1])
+  gem.date    = Time.now.strftime('%Y-%m-%d')
+  
+  gem.summary = "An RDoc template that scales"
+  gem.description = "Hanna is an RDoc implemented in Haml, making its source clean and maintainable. It's built with simplicity, beauty and ease of browsing in mind."
+  
+  gem.files = Dir['Rakefile', 'lib/**/*', 'README*', 'LICENSE*']
+  
+  gem.add_dependency 'rdoc', '~> 2.5.9'
+  gem.add_dependency 'haml', '~> 2.2.8'
+  gem.add_dependency 'rake', '~> 0.8.2'
+  
+  gem.email = 'mislav.marohnic@gmail.com'
+  gem.homepage = 'http://github.com/mislav/' + gem.name
+  gem.authors = ['Mislav Marohnić']
+  
+  gem.has_rdoc = false
+  gem.rubyforge_project = nil
+end

data/lib/hanna.rb

@@ -0,0 +1,323 @@
+# = A better RDoc HTML template
+#
+# Code rewritten by:
+#   Erik Hollensbe <erik@hollensbe.org>
+#
+# RubyGems integration properly done by:
+#   James Tucker (aka raggi)
+#
+# Original 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
+
+module Hanna
+  VERSION = '0.1.13'
+end
+
+require 'pathname'
+require 'haml'
+require 'sass'
+require 'rdoc/rdoc'
+require 'rdoc/generator'
+
+module RDoc #:nodoc:
+  module Generator #:nodoc:
+  end
+end
+
+class RDoc::Generator::Hanna 
+  STYLE            = 'styles.sass'
+  LAYOUT           = 'layout.haml'
+
+  INDEX_PAGE       = 'index.haml'
+  CLASS_PAGE       = 'page.haml'
+  METHOD_LIST_PAGE = 'method_list.haml'
+  FILE_PAGE        = CLASS_PAGE
+  SECTIONS_PAGE    = 'sections.haml'
+
+  FILE_INDEX       = 'file_index.haml'
+  CLASS_INDEX      = 'class_index.haml'
+  METHOD_INDEX     = 'method_index.haml'
+
+  CLASS_DIR        = 'classes'
+  FILE_DIR         = 'files'
+
+  INDEX_OUT        = 'index.html'
+  FILE_INDEX_OUT   = 'fr_file_index.html'
+  CLASS_INDEX_OUT  = 'fr_class_index.html'
+  METHOD_INDEX_OUT = 'fr_method_index.html'
+  STYLE_OUT        = File.join('css', 'style.css')
+
+  # EPIC CUT AND PASTE TIEM NAO -- GG
+  RDoc::RDoc.add_generator( self )
+
+  def self::for( options )
+    new( options )
+  end
+
+  def initialize( options )
+    @options = options
+
+    @templatedir = Pathname.new File.expand_path('../hanna/template_files', __FILE__)
+
+    @files      = nil
+    @classes    = nil
+    @methods    = nil
+    @attributes = nil
+
+    @basedir = Pathname.pwd.expand_path
+  end
+
+  def generate( top_levels )
+    @outputdir = Pathname.new( @options.op_dir ).expand_path( @basedir )
+
+    @files      = top_levels.sort
+    @classes    = RDoc::TopLevel.all_classes_and_modules.sort
+    @methods    = @classes.map(&:method_list).flatten.sort
+    @attributes = @classes.map(&:attributes).flatten.sort
+
+    # Now actually write the output
+    write_static_files
+    generate_indexes
+    generate_class_files
+    generate_file_files
+
+  rescue StandardError => err
+    p [ err.class.name, err.message, err.backtrace.join("\n  ") ]
+    raise
+  end
+
+  def write_static_files
+    css_dir = outjoin('css')
+
+    unless File.directory?(css_dir)
+      FileUtils.mkdir css_dir
+    end
+
+    File.open(File.join(css_dir, 'style.css'), 'w') { |f| f << Sass::Engine.new(File.read(templjoin(STYLE))).to_css }
+  end
+
+  # FIXME refactor
+  def generate_indexes
+    @main_page_uri = @files.find { |f| f.name == @options.main_page }.path rescue ''
+    File.open(outjoin(INDEX_OUT), 'w') { |f| f << haml_file(templjoin(INDEX_PAGE)).to_html(binding) }
+
+    generate_index(FILE_INDEX_OUT,   FILE_INDEX,   'File',   { :files => @files})
+    generate_index(CLASS_INDEX_OUT,  CLASS_INDEX,  'Class',  { :classes => @classes })
+    generate_index(METHOD_INDEX_OUT, METHOD_INDEX, 'Method', { :methods => @methods, :attributes => @attributes })
+  end
+
+  def generate_index(outfile, templfile, index_name, values)
+    values.merge!({
+      :stylesheet => STYLE_OUT,
+      :list_title => "#{index_name} Index"
+    })
+
+    index = haml_file(templjoin(templfile))
+
+    File.open(outjoin(outfile), 'w') do |f| 
+      f << with_layout(values) do
+             index.to_html(binding, values)
+           end
+    end
+  end
+
+  def generate_file_files
+    file_page = haml_file(templjoin(FILE_PAGE))
+    method_list_page = haml_file(templjoin(METHOD_LIST_PAGE))
+
+    # FIXME non-Ruby files
+    @files.each do |file|
+      path = Pathname.new(file.path)
+      stylesheet = Pathname.new(STYLE_OUT).relative_path_from(path.dirname)
+      
+      values = { 
+        :file => file, 
+        :entry => file,
+        :stylesheet => stylesheet,
+        :classmod => nil, 
+        :title => file.base_name, 
+        :list_title => nil,
+        :description => file.description
+      } 
+
+      result = with_layout(values) do 
+        file_page.to_html(binding, :values => values) do 
+          method_list_page.to_html(binding, values) 
+        end
+      end
+
+      # FIXME XXX sanity check
+      dir = path.dirname
+      unless File.directory? dir
+        FileUtils.mkdir_p dir
+      end
+
+      File.open(outjoin(file.path), 'w') { |f| f << result }
+    end
+  end
+
+  def generate_class_files
+    class_page       = haml_file(templjoin(CLASS_PAGE))
+    method_list_page = haml_file(templjoin(METHOD_LIST_PAGE))
+    sections_page    = haml_file(templjoin(SECTIONS_PAGE))
+    # FIXME refactor
+
+    @classes.each do |klass|
+      outfile = classfile(klass)
+      stylesheet = Pathname.new(STYLE_OUT).relative_path_from(outfile.dirname)
+
+      values = { 
+        :file => klass.path, 
+        :entry => klass,
+        :stylesheet => stylesheet,
+        :classmod => klass.type,
+        :title => klass.full_name,
+        :list_title => nil,
+        :description => klass.description,
+        :section => {
+          # FIXME linkify
+          :classlist => '<ol>' + klass.classes_and_modules.inject('') { |x,y| x << '<li>' + y.name + '</li>' } + '</ol>',
+          :constants => klass.constants,
+          :aliases   => klass.method_list.select { |x| x.is_alias_for },
+          :attributes => klass.attributes,
+          :method_list => klass.method_list.select { |x| !x.is_alias_for }
+        }
+      } 
+
+      result = with_layout(values) do 
+        class_page.to_html(binding, :values => values) do 
+          method_list_page.to_html(binding, :values => values) +
+            sections_page.to_html(binding, :values => values)
+        end
+      end
+
+      # FIXME XXX sanity check
+      dir = outfile.dirname
+      unless File.directory? dir
+        FileUtils.mkdir_p dir
+      end
+
+      File.open(outfile, 'w') { |f| f << result }
+    end
+  end
+
+  def with_layout(values)
+    layout = haml_file(templjoin(LAYOUT))
+    layout.to_html(binding, :values => values) { yield }
+  end
+
+  def sanitize_code_blocks(text)
+    text.gsub(/<pre>(.+?)<\/pre>/m) do
+      code = $1.sub(/^\s*\n/, '')
+      indent = code.gsub(/\n[ \t]*\n/, "\n").scan(/^ */).map{ |i| i.size }.min
+      code.gsub!(/^#{' ' * indent}/, '') if indent > 0
+
+        "<pre>#{code}</pre>"
+    end
+  end
+
+  # probably should bring in nokogiri/libxml2 to do this right.. not sure if
+  # it's worth it.
+  def frame_link(content)
+    content.gsub(%r!<a href="http://[^>]*>!).each do |tag|
+      a_tag, rest = tag.split(' ', 2)
+      rest.gsub!(/target="[^"]*"/, '')
+      a_tag + ' target="_top" ' + rest
+    end
+  end
+
+  def class_dir
+    CLASS_DIR
+  end
+
+  def file_dir
+    FILE_DIR
+  end
+
+  def h(html)
+    CGI::escapeHTML(html)
+  end
+
+  # XXX may my sins be not visited upon my sons.
+  def render_class_tree(entries, parent=nil)
+    namespaces = { }
+
+    entries.sort.inject('') do |out, klass|
+      unless namespaces[klass.full_name]
+        if parent
+          text = '<span class="parent">%s::</span>%s' % [parent.full_name, klass.name]
+        else
+          text = klass.name
+        end
+
+        if klass.document_self
+          out << '<li>'
+          out << link_to(text, classfile(klass))
+        end
+
+        subentries = @classes.select { |x| x.full_name[/^#{klass.full_name}::/] }
+        subentries.each { |x| namespaces[x.full_name] = true }
+        out << "\n<ol>" + render_class_tree(subentries, klass) + "\n</ol>"
+
+        if klass.document_self
+          out << '</li>'
+        end
+      end
+
+      out
+    end
+  end
+    
+  def build_javascript_search_index(entries)
+    result = "var search_index = [\n"
+    entries.each do |entry|
+      method_name = entry.name
+      module_name = entry.parent_name
+      # FIXME link
+      html = link_to_method(entry, [classfile(entry.parent), (entry.aref rescue "method-#{entry.html_name}")].join('#'))
+      result << "  { method: '#{method_name.downcase}', " +
+                      "module: '#{module_name.downcase}', " +
+                      "html: '#{html}' },\n"
+    end
+    result << "]"
+    result
+  end
+
+  def link_to(text, url = nil, classname = nil)
+    class_attr = classname ? ' class="%s"' % classname : ''
+
+    if url
+        %[<a target="docwin" href="#{url}"#{class_attr}>#{text}</a>]
+    elsif classname
+        %[<span#{class_attr}>#{text}</span>]
+    else
+      text
+    end
+  end
+
+  # +method_text+ is in the form of "ago (ActiveSupport::TimeWithZone)".
+  def link_to_method(entry, url = nil, classname = nil)
+    method_name = entry.pretty_name rescue entry.name
+    module_name = entry.parent_name rescue entry.name
+    link_to %Q(<span class="method_name">#{h method_name}</span> <span class="module_name">(#{h module_name})</span>), url, classname
+  end
+
+  def classfile(klass)
+    # FIXME sloooooooow
+    Pathname.new(File.join(CLASS_DIR, klass.full_name.split('::')) + '.html')
+  end
+
+  def outjoin(name)
+    File.join(@outputdir, name)
+  end
+
+  def templjoin(name)
+    File.join(@templatedir, name)
+  end
+
+  def haml_file(file)
+    Haml::Engine.new(File.read(file), :format => :html4)
+  end
+end