reacco 0.0.2

data/.gitignore

@@ -0,0 +1 @@
+/doc/

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/HISTORY.md

@@ -0,0 +1,4 @@
+v0.0.2 - Sep 19, 2011
+---------------------
+
+Initial semi-public version.

data/README.md

@@ -0,0 +1,26 @@
+# Reacco
+#### Readme documentation prettifier
+
+In progress. Check out http://ricostacruz.com/sinatra-assetpack for an example.
+
+# API reference
+
+(API reference goes here)
+
+Acknowledgements
+----------------
+
+© 2011, Rico Sta. Cruz. Released under the [MIT 
+License](http://www.opensource.org/licenses/mit-license.php).
+
+Reacco is authored and maintained by [Rico Sta. Cruz][rsc] with help from it's 
+[contributors][c]. It is sponsored by my startup, [Sinefunc, Inc][sf].
+
+ * [My website](http://ricostacruz.com) (ricostacruz.com)
+ * [Sinefunc, Inc.](http://sinefunc.com) (sinefunc.com)
+ * [Github](http://github.com/rstacruz) (@rstacruz)
+ * [Twitter](http://twitter.com/rstacruz) (@rstacruz)
+
+[rsc]: http://ricostacruz.com
+[c]:   http://github.com/rstacruz/reacco/contributors
+[sf]:  http://sinefunc.com

data/Rakefile

@@ -0,0 +1,31 @@
+desc "Invokes the test suite in multiple RVM environments"
+task :'test!' do
+  # Override this by adding RVM_TEST_ENVS=".." in .rvmrc
+  envs = ENV['RVM_TEST_ENVS'] || '1.9.2@reacco,,1.8.7@reacco'
+  puts "* Testing in the following RVM environments: #{envs.gsub(',', ', ')}"
+  system "rvm #{envs} rake test" or abort
+end
+
+desc "Runs tests"
+task :test do
+  Dir['test/*_test.rb'].each { |f| load f }
+end
+
+task :default => :test
+
+gh = "rstacruz/reacco"
+namespace :doc do
+  # http://github.com/rstacruz/reacco
+  desc "Builds the documentation into doc/"
+  task :build do
+    system "reacco -a --github #{gh} --api lib"
+  end
+
+  # http://github.com/rstacruz/git-update-ghpages
+  desc "Posts documentation to GitHub pages"
+  task :deploy => :build do
+    system "git update-ghpages #{gh} -i doc/"
+  end
+end
+
+task :doc => :'doc:build'

data/bin/reacco

@@ -0,0 +1,95 @@
+#!/usr/bin/env ruby
+$:.unshift File.expand_path('../../lib', __FILE__)
+require 'reacco'
+
+module Params
+  def extract(what)   i = index(what) and slice!(i, 2)[1] end;
+end
+ARGV.extend Params
+
+def tip(str)
+  $stderr.write "#{str}\n"
+end
+
+if ARGV == ['-h'] || ARGV == ['--help']
+  tip "Usage: reacco [options]"
+  tip "Generates nice HTML."
+  tip ""
+  tip "Options:"
+  tip "      --literate         Move <pre> blocks to the right."
+  tip "      --toc              Show a table of contents."
+  tip ""
+  tip "Theming:"
+  tip "      --css FILE         Append the CSS from that file to the generated CSS."
+  tip "  -t, --template PATH    The template to use, if you don't want the default."
+  tip ""
+  tip "API extraction:"
+  tip "      --api PATH         Where to get stuff."
+  tip ""
+  tip "More:"
+  tip "      --github REPO      Adds a 'Fork me on GitHub' badge. Repo should be in"
+  tip "                         'username/reponame' format."
+  tip "  -o, --output PATH      Sets the path to put HTML files in. Defaults to 'doc/'."
+  tip ""
+  exit
+
+else
+  # Build options from arguments.
+  switches = [:literate, :toc]
+  docpath  = ARGV.extract('-o') || ARGV.extract('--output') || 'doc'
+  template = ARGV.extract('-t') || ARGV.extract('--template') || nil
+  github   = ARGV.extract('--github') || nil
+  css      = ARGV.extract('--css') || nil
+  awesome  = ARGV.delete('-a')  || ARGV.extract('--awesome')
+  options  = Hash.new
+
+  extract = Array.new
+  while (x = ARGV.extract('--api'))
+    extract << x
+  end
+
+  switches.each do |opt|
+    options[opt] = true  if ARGV.delete("--#{opt}")
+  end
+
+  switches.each { |opt| options[opt] = true }  if awesome
+
+  options[:github] = github  if github
+
+  if ARGV.any?
+    puts "Invalid usage. See `reacco --help` for help."
+    exit 60
+  end
+
+  # Lets find the readme.
+  readme = Reacco::Readme.new(options)
+  unless readme.exists?
+    tip "Readme file not found."
+    exit 60
+  end
+
+  # If we need to extract API, let's do it.
+  if extract.any?
+    blocks = extract.map { |path|
+      Reacco::Extractor.new(Dir["#{path}/**/*"]).blocks
+    }.flatten
+
+    blocks.each { |blk| readme.inject_api_block blk.to_html }
+  end
+
+  # Now let's generate it.
+  gen  = Reacco::Generator.new(readme, docpath, template, css)
+  unless gen.template?
+    tip "Invalid template."
+    tip "A template must at least have an index.xxx page."
+    exit 61
+  end
+
+  gen.write! { |file| tip "* #{file}" }
+
+  # AHHH YYEAAAHHH!
+  tip "Construction complete."
+end
+
+
+#tip Reacco.html(:hgroup => true, :literate => true, :brief => true)

data/data/index.erb

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8" />
+    <title><%= title %></title>
+    <link href="style.css" rel="stylesheet" />
+    <link href='http://fonts.googleapis.com/css?family=Shanti:400|PT+Sans:700,700italic' rel='stylesheet' type='text/css'>
+</head>
+<body class='<%= body_class %>'>
+  <% if github %>
+    <a href="<%= github %>"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://a248.e.akamai.net/assets.github.com/img/e6bef7a091f5f3138b8cd40bc3e114258dd68ddf/687474703a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f7265645f6161303030302e706e67" alt="Fork me on GitHub"></a>
+  <% end %>
+  <div id='all'><%= yield %></div>
+  <script type='text/javascript' src='http://cachedcommons.org/cache/prettify/1.0.0/javascripts/prettify-min.js'></script>
+  <script>prettyPrint();</script>
+</body>
+</html>

data/data/style.css

@@ -0,0 +1,341 @@
+html, body {
+  margin: 0;
+  padding: 0; }
+
+body {
+  background: #fcfcfa;
+  font-family: 'pt sans', sans-serif;
+  color: #444;
+  font-size: 11pt;
+  line-height: 1.5; }
+
+::-moz-selection { background: #88a; color: #fff; text-shadow: none; }
+::selection      { background: #88a; color: #fff; text-shadow: none; }
+
+h1, h2, h3, h4, h5, h6, p, ol, ul, pre, ol>li {
+  max-width: 500px;
+  margin: 20px 0; }
+
+ol, ul {
+  padding-left: 0;
+  margin-left: 30px; }
+
+#all {
+  min-width: 960px;
+  box-sizing: border-box;
+  -moz-box-sizing: border-box;
+  -webkit-box-sizing: border-box;
+  width: 100%;
+  overflow-x: hidden;
+  padding: 40px; }
+
+a, a:visited {
+  text-decoration: none;
+  border-bottom: solid 1px #ccf;
+  color: #46b; }
+
+a:hover {
+  background: #fafae0; }
+
+/* List */
+ul li > p > strong:first-child {
+  display: block;
+  font-size: 1.1em; }
+
+/* Headings */
+h1 {
+  font-family: palatino, serif; }
+
+h1, h2, h3, h4, h5, h6 {
+  text-shadow: 2px 2px 0 rgba(55, 55, 55, 0.1);
+  color: #568;
+  font-weight: normal;
+  font-family: shanti, palatino, serif; }
+
+h3 {
+  color: #77a; }
+
+h4, h5, h6 {
+  color: #88a; }
+
+/* The "(class method)" thing */
+h1 .type, h2 .type, h3 .type, h4 .type, h5 .type, h6 .type {
+  font-size: 9pt;
+  color: #aaa;
+  text-transform: uppercase;
+  margin-left: 10px; }
+
+h2 {
+  max-width: none;
+  padding-top: 30px;
+  margin-top: 40px; }
+
+h3 {
+  max-width: none;
+  padding-top: 10px;
+  margin-top: 40px; }
+
+h1 { font-size: 30pt; }
+h2 { font-size: 23pt; }
+h3 { font-size: 14pt; }
+h4 { font-size: 14pt; }
+h5 { font-size: 10pt; }
+h6 { font-size: 10pt; }
+
+h2+p { margin-top: 0; }
+h2+pre.right+p { margin-top: 0; }
+
+/* Code */
+pre, code {
+  font-family: Monaco, monospace; }
+
+code {
+  text-shadow: 1px 1px 0 rgba(255, 255, 255, 0.99);
+  font-family: 'shanti', sans-serif;
+  color: #9090aa; }
+
+pre > code {
+  color: #60606f;
+  text-shadow: none;
+  font-family: Monaco, monospace;
+  background: 0;
+  padding: 0;
+  border: 0; }
+
+pre {
+  font-size: 9pt;
+  padding-top: 5px;
+  background: transparent; }
+
+/* The header */
+.header h1, .header h2, .header h3,
+.header h4, .header h5, .header h6 {
+  text-shadow: none;
+  line-height: 1.35;
+  margin: 0;
+  padding: 0; }
+
+.header h1 a,
+.header h1 {
+  font-family: 'pt sans', sans-serif;
+  font-weight: bold;
+  color: #779; }
+
+.header h1 a {
+  border-bottom: 0; }
+
+.header h2, .header h3,
+.header h4, .header h5, .header h6 {
+  color: #aab; } /* color: #78b; */
+
+.header h4 {
+  font-size: 1.4em;
+  font-family: palatino, serif;
+  font-style: italic;
+  font-weight: normal; }
+
+/* Literate */
+body.literate h4, body.literate h5, body.literate h6, body.literate p,
+body.literate ol, body.literate ul, body.literate pre {
+  max-width: 400px; }
+
+body.literate pre.right {
+  clear: both;
+  max-width: none;
+  width: 490px;
+  margin-left: 50px;
+  float: right; }
+
+body.literate pre.right code {
+  color: #78a; }
+
+body.literate h1 + pre.right,
+body.literate h2 + pre.right,
+body.literate h3 + pre.right {
+  margin-top: 0; }
+
+h1, h2, h3 {
+  clear: both; }
+
+.clear {
+  clear: both; }
+
+br.post-pre {
+  clear: both; }
+
+h4 { margin-bottom: 5px; }
+h4+p,
+h4+pre.right,
+h4+pre.right+p { margin-top: 0; }
+
+/* Section-wrap */
+section {
+  width: 960px;
+  margin-top: 0;
+  margin-left: 0;
+  padding-left: 40px;
+  margin-left: -40px;
+  padding-right: 9000px; }
+
+section::after {
+  content: '';
+  display: table;
+  clear: both; }
+
+section.h2:nth-child(even) {
+  box-shadow: 0 1px 10px rgba(0, 0, 0, 0.1);
+  background: rgba(255, 255, 255, 0.8); }
+
+section:first-of-type {
+  margin-top: 40px; }
+
+section.h1, section.h2, section.h3 {
+  padding-top: 30px;
+  padding-bottom: 40px;
+  border-top: solid 1px #eee; }
+
+section.h1 {
+  border-top: solid 10px #ddd; }
+
+section.h3 {
+  padding-top: 20px;
+  margin-top: 40px;
+  padding-left: 30px;
+  border-left: solid 10px #e7e7f4;
+  border-top: dotted 1px #ddd; }
+
+section.h3:nth-child(odd) {
+  border-left-color: #d0d0e8; }
+
+section.h3 + section.h3 {
+  margin-top: -20px; }
+
+section.h1>:first-child, section.h2>:first-child, section.h3>:first-child {
+  padding-top: 0;
+  margin-top: 0; }
+
+/* API */
+section.api h2,
+section.api h3 {
+  margin-bottom: 0; }
+
+section.api h2 + p,
+section.api h2 + pre + p,
+section.api h3 + p,
+section.api h3 + pre + p {
+  margin-top: 0; }
+
+h2 .args,
+h3 .args {
+  margin-left: 3px;
+  font-size: 0.9em;
+  margin-right: 15px;
+  color: #aab; }
+
+/* Pretty printing styles. Used with prettify.js. */
+.str { color: #080; }
+.kwd { color: #008; }
+.com { color: #607077; background: rgba(0, 0, 0, 0.05); padding: 1px 3px; }
+.typ { color: #606; }
+.lit { color: #066; }
+.pun { color: #660; }
+.pln { color: #000; }
+.tag { color: #008; }
+.atn { color: #606; }
+.atv { color: #080; }
+.dec { color: #606; }
+
+/* Specify class=linenums on a pre to get line numbering */
+ol.linenums { margin-top: 0; margin-bottom: 0 } /* IE indents via margin-left */
+li.L0, li.L1, li.L2, li.L3, li.L5, li.L6, li.L7, li.L8 { list-style-type: none }
+/* Alternate shading for lines */
+li.L1, li.L3, li.L5, li.L7, li.L9 { background: #eee }
+
+@media print {
+  .str { color: #060; }
+  .kwd { color: #006; font-weight: bold; }
+  .com { color: #600; font-style: italic; }
+  .typ { color: #404; font-weight: bold; }
+  .lit { color: #044; }
+  .pun { color: #440; }
+  .pln { color: #000; }
+  .tag { color: #006; font-weight: bold; }
+  .atn { color: #404; }
+  .atv { color: #060; }
+}
+
+/* TOC */
+body.toc {
+  margin-left: 200px; }
+
+aside#toc {
+  font-size: 0.9em;
+  line-height: 1.7;
+  position: fixed;
+  top: 0;
+  left: 0;
+  bottom: 0;
+  padding: 20px;
+  width: 180px;
+  overflow-y: auto;
+  box-shadow: inset -2px 0 2px rgba(0, 0, 0, 0.1);
+  border-right: solid 1px #ccc;
+  background: #f4f4fa; }
+
+aside#toc h1,
+aside#toc h2,
+aside#toc h3 {
+  overflow: hidden;
+  margin: 10px 0;
+  padding: 0;
+  font-size: 1.1em; }
+
+aside#toc h1 {
+  color: #aaa;
+  text-shadow: none;
+  font-size: 1.3em; }
+
+aside#toc h3 {
+  border-top: solid 1px #ddd;
+  padding-top: 10px; }
+
+aside#toc h2 .type,
+aside#toc h3 .type {
+  margin-left: 0; }
+
+aside#toc ul,
+aside#toc li {
+  margin: 0;
+  padding: 0;
+  list-style-type: none; }
+
+aside#toc h1 a,
+aside#toc h2 a,
+aside#toc h3 a {
+  color: #333; }
+
+aside#toc a {
+  overflow: hidden;
+  display: block;
+  border-bottom: 0;
+  color: #555; }
+
+aside#toc a span.args {
+  display: none; }
+
+aside#toc a span.type {
+  font-size: 0.8em;
+  text-transform: uppercase;
+  color: #999; }
+
+aside#toc .type {
+  float: right; }
+
+aside#toc::-webkit-scrollbar {  
+  height: 15px; width: 15px;
+}
+
+aside#toc::-webkit-scrollbar-thumb {  
+  border-width: 7px 7px 7px 7px;
+  -webkit-border-image: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyJpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMC1jMDYwIDYxLjEzNDc3NywgMjAxMC8wMi8xMi0xNzozMjowMCAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENTNSBNYWNpbnRvc2giIHhtcE1NOkluc3RhbmNlSUQ9InhtcC5paWQ6NDZEMERCMUZGRUI2MTFERkIwQ0RGMkFBNEE3NDlCOUMiIHhtcE1NOkRvY3VtZW50SUQ9InhtcC5kaWQ6NDZEMERCMjBGRUI2MTFERkIwQ0RGMkFBNEE3NDlCOUMiPiA8eG1wTU06RGVyaXZlZEZyb20gc3RSZWY6aW5zdGFuY2VJRD0ieG1wLmlpZDo0NkQwREIxREZFQjYxMURGQjBDREYyQUE0QTc0OUI5QyIgc3RSZWY6ZG9jdW1lbnRJRD0ieG1wLmRpZDo0NkQwREIxRUZFQjYxMURGQjBDREYyQUE0QTc0OUI5QyIvPiA8L3JkZjpEZXNjcmlwdGlvbj4gPC9yZGY6UkRGPiA8L3g6eG1wbWV0YT4gPD94cGFja2V0IGVuZD0iciI/PpHo8kwAAACBSURBVHjaYvz//z8DJYCJgUJAsQEsyBxGRkYwBcS6QKwBxLJQqcdAfAOILwPxf2RvM6JwICbYA7EDDgsPAPFBZBPQvaCLRzMDVE4XXxhoEOFtDXwGyBJhgCxNo/ExEXoe4zPgBhEG3MBnwGVoVDHgicbLKGkHLR1QlpCGZmYCCDAAxuMoE4WhhWUAAAAASUVORK5CYII=) 7 7 7 7 round round;
+}

data/lib/reacco/extractor/block.rb

@@ -0,0 +1,84 @@
+# Reacco::Extractor::Block [class]
+# An extractor block.
+#
+module Reacco
+  class Extractor
+    class Block
+      # body [method]
+      # Returns the body text as a raw string.
+      attr_reader :body
+
+      # title [method]
+      # Returns the title of the block.
+      attr_reader :title
+      attr_reader :type
+      attr_reader :parent
+      attr_reader :args
+
+      def initialize(options)
+        @body        = options[:body]
+        @type        = options[:type] && options[:type].downcase
+        @args        = options[:args]
+        @title       = options[:title]
+        @parent      = options[:parent]
+        @tag         = options[:tag]
+        @source_line = options[:source_line]
+        @source_path = options[:source_path]
+      end
+
+      # children [method]
+      # Returns an array of child blocks.
+      def children
+        @children ||= Array.new
+      end
+
+      # << [method]
+      # Adds a block to it's children.
+      def <<(blk)
+        children << blk
+      end
+
+      def raw_html
+        Reacco.markdown.render(@body)
+      end
+
+      # Nokogiri node.
+      def doc
+        @doc ||= Nokogiri::HTML(raw_html)
+      end
+
+      def transform!
+        # Create heading.
+        name = @tag
+        node = Nokogiri::XML::Node.new(name, doc)
+        node['class'] = 'api'
+        node.content  = title
+
+        # Add '(args)'.
+        if args
+          span = Nokogiri::XML::Node.new("span", doc)
+          span['class'] = 'args'
+          span.content = args
+          node.add_child span
+        end
+
+        # Add '(class method)'.
+        span = Nokogiri::XML::Node.new("span", doc)
+        span['class'] = 'type'
+        span.content = type
+        node.add_child Nokogiri::XML::Text.new(' ', doc)
+        node.add_child span
+
+        # Add heading.
+        doc.at_css('body>*:first-child').add_previous_sibling node
+        doc
+      end
+
+      # to_html [method]
+      # Returns the raw HTML to be included in the documentation.
+      def to_html
+        @to_html ||= transform!.at_css('body').inner_html
+      end
+    end
+  end
+end

data/lib/reacco/extractor.rb

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+
+require 'ostruct'
+require 'fileutils'
+module Reacco
+  # Reacco::Extractor [class]
+  # Extracts comments from list of files.
+  #
+  # #### Instantiating
+  # Call the constructor with a list of files.
+  #
+  #     ex = Extractor.new(Dir['./**/*.rb'])
+  #
+  class Extractor
+    autoload :Block, 'reacco/extractor/block'
+
+    def initialize(files, root=nil, options={})
+      @files = files.sort
+      @root  = File.realpath(root || Dir.pwd)
+    end
+
+    # blocks [method]
+    # Returns an array of `Block` instances.
+    #
+    #     ex.blocks
+    #     ex.blocks.map { |b| puts "file: #{b.file}" }
+    #
+    def blocks
+      @blocks ||= begin
+        @files.map do |file|
+          if File.file?(file)
+            input = File.read(file)
+            get_blocks(input, unroot(file))
+          end
+        end.compact.flatten
+      end
+    end
+
+  private
+    def unroot(fn)
+      (File.realpath(fn))[@root.size..-1]
+    end
+
+    # get_blocks(str, [filename]) [private method]
+    # Returns the documentation blocks in a given `str`ing.
+    # If `filename` is given, it will be set as the *source_file*.
+    #
+    def get_blocks(str, filename=nil)
+      arr    = get_comment_blocks(str)
+
+      arr.map do |hash|
+        block = hash[:block]
+
+        # Ensure the first line matches.
+        # This matches:
+        #   "### name [type]"
+        #   "## name(args) [type]"
+        re = /^(\#{1,6}) (.*?) ?(\(.*?\))? ?(?:\[([a-z ]+)\])?$/
+        block.first =~ re  or next
+
+        blk = Extractor::Block.new \
+          :type        => $4,
+          :tag         => "h#{$1.strip.size}",
+          :title       => $2,
+          :args        => $3,
+          :source_line => hash[:line] + block.size + 1,
+          :source_file => filename,
+          :body        => (block[1..-1].join("\n") + "\n")
+
+        blk
+    end.compact
+    end
+
+    # get_comment_blocks (private method)
+    # Returns contiguous comment blocks.
+    #
+    # Returns an array of hashes that look like
+    # `{ :block => [line1, line2...], :line => (line number) }`
+    #
+    def get_comment_blocks(str)
+      chunks = Array.new
+      i = 0
+
+      str.split("\n").each_with_index { |s, line|
+        if s =~ /^\s*(?:\/\/\/?|##?) ?(.*)$/
+          chunks[i] ||= { :block => Array.new, :line => line }
+          chunks[i][:block] << $1
+        else
+          i += 1  if chunks[i]
+        end
+      }
+
+      chunks.compact
+    end
+  end
+end

data/lib/reacco/filters/brief.rb

@@ -0,0 +1,12 @@
+module Reacco
+  module Filters
+    module Brief
+      # Makes the first <p> a brief.
+      def brief_first_p(html)
+        p = html.at_css('body>p')
+        p['class'] = "#{p['class']} brief"  if p
+        html
+      end
+    end
+  end
+end

data/lib/reacco/filters/headingid.rb

@@ -0,0 +1,13 @@
+module Reacco
+  module Filters
+    module HeadingID
+      def heading_id(html)
+        html.css('h1, h2, h3').each do |h|
+          h['id'] = slugify(h.content)
+        end
+
+        html
+      end
+    end
+  end
+end

data/lib/reacco/filters/hgroup.rb

@@ -0,0 +1,26 @@
+module Reacco
+  module Filters
+    module Hgroup
+      # Wraps the first headings into an <hgroup>.
+      def wrap_hgroup(html)
+        nodes = Array.new
+        html.css('body>*').each { |node|
+          # Consume all headings.
+          if %w(h1 h2 h3 h4 h5 h6).include?(node.name)
+            nodes << node.to_s
+            node.remove
+
+          # Once the headings stop, dump them into an <hgroup>.
+          # Ah, and eat an <hr> if there is one.
+          else
+            node.before("<hgroup class='header'>#{nodes.join('')}</hgroup>")  if nodes.any?
+            node.remove  if node.name == 'hr'
+            break
+          end
+        }
+
+        html
+      end
+    end
+  end
+end

data/lib/reacco/filters/literate.rb

@@ -0,0 +1,36 @@
+module Reacco
+  module Filters
+    module Literate
+      # Moves pre's after headers.
+      def move_pre(html)
+        anchor   = nil
+        position = nil
+
+        html.css('body>*').each_cons(2) { |(node, nxt)|
+          # Once we find the <pre>, move it.
+          if node.name == 'pre' && anchor && anchor != node && !(node['class'].to_s =~ /full/)
+            node.after "<br class='post-pre'>"
+
+            nxt['class']    = "#{nxt['class']} after-pre"  if nxt
+            node['class']   = "#{node['class']} right"
+
+            anchor.send position, node
+            anchor = nil
+
+          # If we find one of these, put the next <pre> after it.
+          elsif %w(h1 h2 h3 h4 pre).include?(node.name)
+            anchor   = node
+            position = :add_next_sibling
+
+          # If we find one of these, put the <pre> before it.
+          elsif node['class'].to_s.include?('after-pre')
+            anchor   = node
+            position = :add_previous_sibling
+          end
+        }
+
+        html
+      end
+    end
+  end
+end

data/lib/reacco/filters/prelang.rb

@@ -0,0 +1,11 @@
+module Reacco
+  module Filters
+    module PreLang
+      # Adds prettify classes.
+      def pre_lang(html)
+        html.css('pre').each { |pre| pre['class'] = "#{pre['class']} lang-#{pre['class']} prettyprint" }
+        html
+      end
+    end
+  end
+end

data/lib/reacco/filters/sections.rb

@@ -0,0 +1,56 @@
+module Reacco
+  module Filters
+    module Sections
+      # Wraps in sections.
+      def section_wrap(html)
+        %w(h1 h2 h3 h4 h5).each do |h|
+          nodes = html.css(h)
+          nodes.each do |alpha|
+            # For those affected by --hgroup, don't bother.
+            next  if alpha.ancestors.any? { |tag| tag.name == 'hgroup' }
+            next  unless alpha.parent
+
+            # Find the boundary, and get the nodes until that one.
+            omega         = from_x_until(alpha, alpha.name)
+            section_nodes = between(alpha, omega)
+
+            # Create the <section>.
+            section = Nokogiri::XML::Node.new('section', html)
+            section['class'] = "#{alpha['class']} #{h} #{slugify alpha.content}"
+            alpha.add_previous_sibling(section)
+            section_nodes.each { |tag| section.add_child tag }
+          end
+        end
+
+        html
+      end
+
+    private
+      def from_x_until(alpha, name)
+        omega = nil
+        n = alpha
+
+        while true
+          n = n.next_sibling
+          break if n.nil? || n.name == name
+          omega = n
+        end
+
+        omega
+      end
+
+      def between(first, last)
+        nodes   = Array.new
+        started = false
+
+        first.parent.children.each do |node|
+          started = true  if node == first
+          nodes << node  if started
+          break  if node == last
+        end
+
+        nodes
+      end
+    end
+  end
+end

data/lib/reacco/filters/toc.rb

@@ -0,0 +1,54 @@
+module Reacco
+  module Filters
+    module TOC
+      def make_toc(contents)
+        aside = Nokogiri::XML::Node.new('aside', contents)
+        aside['id'] = 'toc'
+
+        # Header
+        title = (h1 = contents.at_css('h1')) && h1.text || File.basename(Dir.pwd)
+        aside.inner_html = "#{aside.inner_html}<h1>#{title}</h1>"
+
+        contents.xpath('//body/section').each { |tag|
+          aside.inner_html = "#{aside.inner_html}#{make_section tag}"
+        }
+
+        contents.at_css('body').add_child aside
+
+        contents
+      end
+
+      def linkify(h)
+        href = slugify(h.content)
+        "<a href='##{href}'>#{h.inner_html}</a>"
+      end
+
+      def make_section(section)
+        h     = section.at_css('h1, h2, h3')
+        return ''  unless h
+        level = h.name[1]  # 1 | 2 | 3
+        return ''  unless %w(1 2 3).include?(level)
+        name  = h.content.strip
+
+        out = case level
+        when "1"
+          [ "<h2>#{linkify h}</h2>",
+            section.css('section.h2').map { |s| make_section s }
+          ]
+        when "2"
+          [ "<nav class='level-#{level}'>",
+            "<h3>#{linkify h}</h3>",
+            "<ul>",
+            section.css('section.h3').map { |s| make_section s },
+            "</ul>",
+            "</nav>"
+          ]
+        when "3"
+          [ "<li>#{linkify h}</li>" ]
+        end
+
+        out.flatten.join "\n"
+      end
+    end
+  end
+end

data/lib/reacco/generator.rb

@@ -0,0 +1,68 @@
+module Reacco
+  class Generator
+    def initialize(readme, dir, template=nil, css=nil)
+      @readme   = readme
+      @dir      = dir
+      @css      = css
+      @template = template || Reacco.root('data')
+    end
+
+    # Returns the HTML contents.
+    def html
+      file = Dir["#{@template}/index.*"].first
+      raise "No index file found in template path."  unless file
+
+      tpl  = Tilt.new(file)
+      out  = tpl.render({}, @readme.locals) { @readme.html }
+    end
+
+    # Writes to the output directory.
+    def write!(&blk)
+      yield "#{@dir}/index.html"
+      write_to "#{@dir}/index.html", html
+      copy_files &blk
+      append_css   if @css
+    end
+
+    def template?
+      File.directory?(@template) && Dir["#{@template}/index.*"].first
+    end
+
+    # Adds the CSS file to the style.css file.
+    def append_css
+      contents = File.read(@css)
+      File.open("#{@dir}/style.css", 'a+') { |f| f.write "\n/* Custom */\n#{contents}" }
+    end
+
+    def copy_files(&blk)
+      files = Dir.chdir(@template) { Dir['**/*'] }
+
+      # For each of the template files...
+      files.each do |f|
+        next  if File.basename(f)[0] == '_'
+        next  if File.fnmatch('index.*', f)
+        ext = File.extname(f)[1..-1]
+
+        fullpath = File.join @template, f
+
+        # Try to render it with Tilt if possible.
+        if Tilt.mappings.keys.include?(ext)
+          contents = Tilt.new(fullpath).render
+          outfile  = f.match(/^(.*)(\.[^\.]+)$/) && $1
+        else
+          contents = File.read(fullpath)
+          outfile  = f
+        end
+
+        yield "#{@dir}/#{outfile}"
+        write_to "#{@dir}/#{outfile}", contents
+      end
+    end
+
+  private
+    def write_to(path, data)
+      FileUtils.mkdir_p File.dirname(path)
+      File.open(path, 'w') { |f| f.write data }
+    end
+  end
+end

data/lib/reacco/readme.rb

@@ -0,0 +1,150 @@
+# ## Reacco::Readme [class]
+# A readme file.
+module Reacco
+  class Readme
+    def initialize(options={})
+      @file    = options.delete(:file)  if options[:file]
+      @options = options
+    end
+    
+    # ### file [method]
+    # The path to the README file. Returns nil if not available.
+    def file
+      @file ||= (Dir['README.*'].first || Dir['readme.*'].first || Dir['README'].first)
+    end
+
+    def file=(file)
+      @file = file
+    end
+
+    # ### switches [method]
+    # The switches, like 'literate' and 'hgroup'. Returns an array of strings.
+    def switches
+      @options.keys.map { |k| k.to_s }
+    end
+
+    # ### exists? [method]
+    # Returns true if the file (given in the constructor) exists.
+    def exists?
+      file && File.exists?(file)
+    end
+
+    # ### raw [method]
+    # Returns raw Markdown markup.
+    def raw
+      @raw ||= File.read(file)
+    end
+
+    # ### title [method]
+    # Returns a string of the title of the document (the first h1).
+    def title
+      @title ||= begin
+        h1 = (h1 = doc.at_css('h1')) && h1.text
+        h1 || File.basename(Dir.pwd)
+      end
+    end
+
+    def title?
+      title.to_s.size > 0
+    end
+
+    # ### raw_html [method]
+    # Raw HTML data.
+    def raw_html
+      @raw_html ||= markdown.render(raw)
+    end
+
+    def raw_html=(str)
+      @raw_html = str
+    end
+
+    # ### inject_api_block [method]
+    # Adds an API block. Takes an `html` argument.
+    def inject_api_block(html)
+      @api_blocks = "#{api_blocks}\n#{html}\n"
+    end
+
+    def api_blocks
+      @api_blocks ||= ""
+    end
+
+    # ### doc [method]
+    # Returns HTML as a Nokogiri document.
+    def doc(options={})
+      @doc ||= begin
+        add_api(api_blocks)
+        html = Nokogiri::HTML(raw_html)
+
+        html = pre_lang(html)
+        html = heading_id(html)
+        html = wrap_hgroup(html)
+        html = move_pre(html)       if @options[:literate]
+        html = brief_first_p(html)
+        html = section_wrap(html)
+        html = make_toc(html)       if @options[:toc]
+
+        html
+      end
+    end
+
+    # ### html [method]
+    # Returns body's inner HTML.
+    def html
+      doc.at_css('body').inner_html
+    end
+
+    # ### github [method]
+    # Returns the GitHub URL, or nil if not applicable.
+    def github
+      "https://github.com/#{@options[:github]}"  if @options[:github]
+    end
+
+    # Returns locals for the template.
+    def locals
+      { :title      => title,
+        :body_class => switches.join(' '), 
+        :github     => github }
+    end
+
+  private
+    include Filters::Brief
+    include Filters::Sections
+    include Filters::Hgroup
+    include Filters::Literate
+    include Filters::PreLang
+    include Filters::HeadingID
+    include Filters::TOC
+
+    # Puts `blocks` inside `raw_html`.
+    def add_api(blocks)
+      re1 = %r{^.*api reference goes here.*$}i
+      re2 = %r{^.*#api_reference.*$}i
+
+      if raw_html =~ re1
+        raw_html.gsub! re1, blocks
+      elsif raw_html =~ re2
+        raw_html.gsub! re2, blocks
+      else
+        self.raw_html = "#{raw_html}\n#{blocks}"
+      end
+    end
+
+    # ### markdown [private method]
+    # Returns the Markdown processor.
+    #
+    #     markdown.render(md)
+    #
+    def markdown
+      Reacco.markdown
+    end
+
+    # ### slugify [private method]
+    # Turns text into a slug.
+    #
+    #     "Install instructions" => "install_instructions"
+    #
+    def slugify(str)
+      str.downcase.scan(/[a-z0-9\-]+/).join('_')
+    end
+  end
+end

data/lib/reacco/version.rb

@@ -0,0 +1,5 @@
+module Reacco
+  def self.version
+    "0.0.2"
+  end
+end

data/lib/reacco.rb

@@ -0,0 +1,44 @@
+require 'nokogiri'
+require 'redcarpet'
+require 'tilt'
+require 'ostruct'
+require 'fileutils'
+
+# ## Reacco [module]
+# This is the main module.
+#
+module Reacco
+  extend self
+
+  # ### root [class method]
+  # Returns the root path of the Reacco gem.
+  # You may pass additional parameters.
+  #
+  #     Reacco.root      #=> '/usr/local/ruby/gems/reacco-0.0.1'
+  #
+  def root(*a)
+    File.join File.expand_path('../../', __FILE__), *a
+  end
+
+  # ### markdown [class method]
+  # Returns the Redcarpet Markdown processor.
+  def markdown
+    Redcarpet::Markdown.new(Redcarpet::Render::HTML,
+      :fenced_code_blocks => true)
+  end
+
+  autoload :Readme,       'reacco/readme'
+  autoload :Generator,    'reacco/generator'
+  autoload :Extractor,    'reacco/extractor'
+
+  module Filters
+    autoload :Brief,      'reacco/filters/brief'
+    autoload :Sections,   'reacco/filters/sections'
+    autoload :Hgroup,     'reacco/filters/hgroup'
+    autoload :Literate,   'reacco/filters/literate'
+    autoload :PreLang,    'reacco/filters/prelang'
+    autoload :HeadingID,  'reacco/filters/headingid'
+    autoload :TOC,        'reacco/filters/toc'
+  end
+end
+

data/reacco.gemspec

@@ -0,0 +1,17 @@
+require './lib/reacco/version'
+
+Gem::Specification.new do |s|
+  s.name = "reacco"
+  s.version = Reacco.version
+  s.summary = %{Readme prettifier.}
+  s.description = %Q{Reacco makes your readme's pretty.}
+  s.authors = ["Rico Sta. Cruz"]
+  s.email = ["rico@sinefunc.com"]
+  s.homepage = "http://github.com/rstacruz/reacco"
+  s.files = `git ls-files`.strip.split("\n")
+  s.executables = Dir["bin/*"].map { |f| File.basename(f) }
+
+  s.add_dependency 'redcarpet', '~> 2.0.0b3'
+  s.add_dependency 'nokogiri',  '~> 1.5'
+  s.add_dependency 'tilt'
+end

data/test/blocks_test.rb

@@ -0,0 +1,18 @@
+require File.expand_path('../test_helper', __FILE__)
+
+class BlocksTest < UnitTest
+  setup do
+    @ex = Reacco::Extractor.new(Dir[root 'lib/**/*.rb'])
+  end
+
+  should "extract comments" do
+    # From Reacco.root
+    block = @ex.blocks.detect { |blk| blk.title == "root" && blk.type == "class method" }
+    assert ! block.nil?
+  end
+
+  should "htmlize properly" do
+    block = @ex.blocks.detect { |blk| blk.title == "root" && blk.type == "class method" }
+    p block.to_html
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,9 @@
+$:.unshift File.expand_path('../../lib', __FILE__)
+require 'contest'
+require 'reacco'
+
+class UnitTest < Test::Unit::TestCase
+  def root(*a)
+    Reacco.root *a
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: reacco
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+  prerelease: 
+platform: ruby
+authors:
+- Rico Sta. Cruz
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-09-18 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: &2156349300 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.0.0b3
+  type: :runtime
+  prerelease: false
+  version_requirements: *2156349300
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: &2156348320 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2156348320
+- !ruby/object:Gem::Dependency
+  name: tilt
+  requirement: &2156347220 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2156347220
+description: Reacco makes your readme's pretty.
+email:
+- rico@sinefunc.com
+executables:
+- reacco
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- HISTORY.md
+- README.md
+- Rakefile
+- bin/reacco
+- data/index.erb
+- data/style.css
+- lib/reacco.rb
+- lib/reacco/extractor.rb
+- lib/reacco/extractor/block.rb
+- lib/reacco/filters/brief.rb
+- lib/reacco/filters/headingid.rb
+- lib/reacco/filters/hgroup.rb
+- lib/reacco/filters/literate.rb
+- lib/reacco/filters/prelang.rb
+- lib/reacco/filters/sections.rb
+- lib/reacco/filters/toc.rb
+- lib/reacco/generator.rb
+- lib/reacco/readme.rb
+- lib/reacco/version.rb
+- reacco.gemspec
+- test/blocks_test.rb
+- test/test_helper.rb
+homepage: http://github.com/rstacruz/reacco
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Readme prettifier.
+test_files: []