reacco 0.0.2 → 0.0.3

data/HISTORY.md

@@ -1,3 +1,12 @@
+v0.0.3 - Sep 19, 2011
+---------------------
+
+### Added:
+  * Support Google Analytics.
+
+### Fixed:
+  * CSS issues (float drops, the sectioning being crappy).
+
 v0.0.2 - Sep 19, 2011
 ---------------------
 

data/README.md

@@ -1,11 +1,95 @@
-# Reacco
+# [Reacco](http://ricostacruz.com/reacco)
 #### Readme documentation prettifier
 
-In progress. Check out http://ricostacruz.com/sinatra-assetpack for an example.
+Reacco is a dead simple documentation generator that lets you document your 
+project using Markdown.
+
+## Usage
+
+#### Installation
+Install Reacco first. It is a Ruby gem.
+
+    $ gem install reacco
+
+#### Generation
+To generate documentation, type `reacco`. This takes your `README.md` file and 
+prettifies it.
+
+    $ reacco
+
+#### Literate style blocks
+To make literate-style blocks (that is, code on the right, explanation on the
+left), use `reacco --literate`.
+
+    $ reacco --literate
+
+## Documenting API
+To extract documentation from your code files, add `--api <path here>`. This 
+extracts comment blocks from files in that path.
+
+As Reacco only parses out Markdown from your comments, almost all programming 
+languages are supported. It does not care about code at all, just comments.
+
+    $ reacco --literate --api lib/
+
+#### Documenting classes
+You will need to add Markdown comment blocks to your code. The first line needs 
+to be a Markdown heading in the form of `### <heading name>`.
+
+Classes are often made to be H2's.
+
+``` ruby
+# ## Reacco [class]
+# The main class.
+#
+# Class documentation goes here in Markdown form.
+#
+class Reacco
+  ...
+end
+```
+
+#### Documenting class methods
+Class methods are often made as H3's. Sub-sections are often always H4's.
+
+``` ruby
+# ## Reacco [class]
+# The main class.
+#
+class Reacco
+  # ### version [class method]
+  # Returns a string of the library's version.
+  #
+  # #### Example
+  # This example returns the version.
+  #
+  #     Reacco.version
+  #     #=> "0.0.1"
+  #
+  def self.version
+    ...
+  end
+end
+```
+
+#### Adding the placeholder
+To specify where the docs will be in the README, put a line with the text 
+`[](#api_reference)`. This will tell Reacco where to "inject" your API 
+documentation.
+
+    # README.md:
+    Please see http://you.github.com/project. [](#api_reference)
 
 # API reference
 
-(API reference goes here)
+For usage and API reference, please see http://ricostacruz.com/reacco. [](#api_reference)
+
+Warning
+-------
+
+**Here be dragons!** this is mostly made for my own projects, so I may change 
+things quite often (though I'd try to be mostly API-compatible with older
+versions).
 
 Acknowledgements
 ----------------

data/Rakefile

@@ -18,7 +18,8 @@ namespace :doc do
   # http://github.com/rstacruz/reacco
   desc "Builds the documentation into doc/"
   task :build do
-    system "reacco -a --github #{gh} --api lib"
+    analytics = "--analytics #{ENV['ANALYTICS_ID']}"  if ENV['ANALYTICS_ID']
+    system "reacco -a --github #{gh} #{analytics} --api lib"
   end
 
   # http://github.com/rstacruz/git-update-ghpages

data/bin/reacco

@@ -27,6 +27,7 @@ if ARGV == ['-h'] || ARGV == ['--help']
   tip "      --api PATH         Where to get stuff."
   tip ""
   tip "More:"
+  tip "      --analytics ID     Google Analytics ID."
   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/'."
@@ -35,13 +36,14 @@ if ARGV == ['-h'] || ARGV == ['--help']
 
 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
+  switches  = [:literate, :toc]
+  docpath   = ARGV.extract('-o') || ARGV.extract('--output') || 'doc'
+  template  = ARGV.extract('-t') || ARGV.extract('--template') || nil
+  analytics = ARGV.extract('--analytics') || 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'))
@@ -54,7 +56,8 @@ else
 
   switches.each { |opt| options[opt] = true }  if awesome
 
-  options[:github] = github  if github
+  options[:github]    = github     if github
+  options[:analytics] = analytics  if analytics
 
   if ARGV.any?
     puts "Invalid usage. See `reacco --help` for help."

data/data/index.erb

@@ -5,6 +5,19 @@
     <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'>
+    <% if analytics %>
+      <script type='text/javascript'>
+        var _gaq = _gaq || [];
+        _gaq.push(['_setAccount', '<%= analytics %>']);
+        _gaq.push(['_trackPageview']);
+
+        (function() {
+          var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+          ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+          var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+        })();
+      </script>
+    <% end %>
 </head>
 <body class='<%= body_class %>'>
   <% if github %>

data/data/style.css

@@ -285,7 +285,6 @@ aside#toc {
 aside#toc h1,
 aside#toc h2,
 aside#toc h3 {
-  overflow: hidden;
   margin: 10px 0;
   padding: 0;
   font-size: 1.1em; }
@@ -295,12 +294,14 @@ aside#toc h1 {
   text-shadow: none;
   font-size: 1.3em; }
 
+aside#toc h2,
 aside#toc h3 {
   border-top: solid 1px #ddd;
   padding-top: 10px; }
 
 aside#toc h2 .type,
 aside#toc h3 .type {
+  margin-top: 2px;
   margin-left: 0; }
 
 aside#toc ul,
@@ -315,7 +316,10 @@ aside#toc h3 a {
   color: #333; }
 
 aside#toc a {
+  height: 1.6em;
   overflow: hidden;
+  line-height: 1.6em;
+  position: relative;
   display: block;
   border-bottom: 0;
   color: #555; }
@@ -324,11 +328,10 @@ aside#toc a span.args {
   display: none; }
 
 aside#toc a span.type {
-  font-size: 0.8em;
+  font-weight: normal;
+  color: #999;
   text-transform: uppercase;
-  color: #999; }
-
-aside#toc .type {
+  font-size: 8pt;
   float: right; }
 
 aside#toc::-webkit-scrollbar {  

data/lib/reacco.rb

@@ -14,14 +14,20 @@ module Reacco
   # Returns the root path of the Reacco gem.
   # You may pass additional parameters.
   #
-  #     Reacco.root      #=> '/usr/local/ruby/gems/reacco-0.0.1'
+  #     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.
+  # Returns the Redcarpet Markdown processor.  This is an instance of
+  # `Redcarpet` with all the right options plugged in.
+  #
+  #     Reacco.markdown
+  #     #=> #<Redcarpet::Markdown ...>
+  #
   def markdown
     Redcarpet::Markdown.new(Redcarpet::Render::HTML,
       :fenced_code_blocks => true)

data/lib/reacco/filters/sections.rb

@@ -3,7 +3,8 @@ module Reacco
     module Sections
       # Wraps in sections.
       def section_wrap(html)
-        %w(h1 h2 h3 h4 h5).each do |h|
+        headings = %w(h1 h2 h3 h4 h5)
+        headings.each do |h|
           nodes = html.css(h)
           nodes.each do |alpha|
             # For those affected by --hgroup, don't bother.
@@ -11,7 +12,7 @@ module Reacco
             next  unless alpha.parent
 
             # Find the boundary, and get the nodes until that one.
-            omega         = from_x_until(alpha, alpha.name)
+            omega         = from_x_until(alpha, *headings[0..headings.index(alpha.name)])
             section_nodes = between(alpha, omega)
 
             # Create the <section>.
@@ -26,13 +27,19 @@ module Reacco
       end
 
     private
-      def from_x_until(alpha, name)
+      def from_x_until(alpha, *names)
         omega = nil
         n = alpha
 
         while true
           n = n.next_sibling
-          break if n.nil? || n.name == name
+          break if n.nil?
+
+          name = n.name
+          if name == 'section'
+            name = (h = n.at_css('h1, h2, h3, h4, h5, h6')) && h.name
+          end
+          break if !name || names.include?(name)
           omega = n
         end
 

data/lib/reacco/readme.rb

@@ -1,5 +1,21 @@
 # ## Reacco::Readme [class]
 # A readme file.
+#
+# #### Instanciating
+# This is often instanciated by the `reacco` executable, but you can instantiate
+# it yourself like so. It's assumed the the base dir will be the current working
+# directory.
+#
+#     readme = Reacco::Readme.new
+#     readme = Reacco::Readme.new [OPTIONS HASH]
+#
+# #### Options
+# Avaiable options are *(all are optional)*:
+#
+#  * `file` - String *(the filename of the README file)*
+#  * `literate` - Boolean
+#  * `toc` - Boolean
+#
 module Reacco
   class Readme
     def initialize(options={})
@@ -8,7 +24,10 @@ module Reacco
     end
     
     # ### file [method]
-    # The path to the README file. Returns nil if not available.
+    # The path to the README file. Returns `nil` if not available.
+    #
+    #     readme.file      #=> "README.md"
+    #     
     def file
       @file ||= (Dir['README.*'].first || Dir['readme.*'].first || Dir['README'].first)
     end
@@ -18,25 +37,42 @@ module Reacco
     end
 
     # ### switches [method]
-    # The switches, like 'literate' and 'hgroup'. Returns an array of strings.
+    # The switches, like *literate* and *toc*. Returns an array of strings.
+    #
+    #     readme.switches  #=> [ 'literate' ]
     def switches
       @options.keys.map { |k| k.to_s }
     end
 
     # ### exists? [method]
     # Returns true if the file (given in the constructor) exists.
+    #
+    #     readme = Readme.new :file => 'non-existent-file.txt'
+    #     readme.exists?
+    #     #=> false (maybe)
+    #
     def exists?
       file && File.exists?(file)
     end
 
     # ### raw [method]
     # Returns raw Markdown markup.
+    #
+    #     readme.raw
+    #     #=> "# My project\n#### This is my project\n\n..."
+    #
     def raw
       @raw ||= File.read(file)
     end
 
     # ### title [method]
-    # Returns a string of the title of the document (the first h1).
+    # Returns a string of the title of the document. Often, this is the first
+    # H1, but if that's not available, then it is inferred from the current
+    # directory's name.
+    #
+    #     readme.title
+    #     #=> "My project"
+    #
     def title
       @title ||= begin
         h1 = (h1 = doc.at_css('h1')) && h1.text
@@ -49,7 +85,12 @@ module Reacco
     end
 
     # ### raw_html [method]
-    # Raw HTML data.
+    # Returns a string of the raw HTML data built from the markdown source.
+    # This does not have the transformations applied to it yet.
+    #
+    #     readme.raw_html
+    #     #=> "<h1>My project</h1>..."
+    #
     def raw_html
       @raw_html ||= markdown.render(raw)
     end
@@ -60,6 +101,7 @@ module Reacco
 
     # ### 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
@@ -68,8 +110,12 @@ module Reacco
       @api_blocks ||= ""
     end
 
-    # ### doc [method]
-    # Returns HTML as a Nokogiri document.
+    # ### doc([options]) [method]
+    # Returns HTML as a Nokogiri document with all the transformations applied.
+    #
+    #     readme.doc
+    #     #=> #<Nokogiri::HTML ...>
+    #
     def doc(options={})
       @doc ||= begin
         add_api(api_blocks)
@@ -88,21 +134,35 @@ module Reacco
     end
 
     # ### html [method]
-    # Returns body's inner HTML.
+    # Returns body's inner HTML *with* transformatinos.
+    #
+    #     readme.raw_html
+    #     #=> "<h1>My project</h1>..."
+    #
     def html
       doc.at_css('body').inner_html
     end
 
     # ### github [method]
     # Returns the GitHub URL, or nil if not applicable.
+    #
+    #     readme.github
+    #     #=> "https://github.com/rstacruz/reacco"
+    #
     def github
       "https://github.com/#{@options[:github]}"  if @options[:github]
     end
 
-    # Returns locals for the template.
+    # ### locals [method]
+    # Returns a hash with the local variables to be used for the ERB template.
+    #
+    #     readme.locals
+    #     #=> { :title => 'My project', ... }
+    #
     def locals
       { :title      => title,
         :body_class => switches.join(' '), 
+        :analytics  => @options[:analytics],
         :github     => github }
     end
 
@@ -118,7 +178,7 @@ module Reacco
     # Puts `blocks` inside `raw_html`.
     def add_api(blocks)
       re1 = %r{^.*api reference goes here.*$}i
-      re2 = %r{^.*#api_reference.*$}i
+      re2 = %r{^.*href=['"]#api_reference['"].*$}i
 
       if raw_html =~ re1
         raw_html.gsub! re1, blocks

data/lib/reacco/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reacco
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-18 00:00:00.000000000Z
+date: 2011-09-19 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redcarpet
-  requirement: &2156349300 !ruby/object:Gem::Requirement
+  requirement: &2156896460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 2.0.0b3
   type: :runtime
   prerelease: false
-  version_requirements: *2156349300
+  version_requirements: *2156896460
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &2156348320 !ruby/object:Gem::Requirement
+  requirement: &2156895880 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: '1.5'
   type: :runtime
   prerelease: false
-  version_requirements: *2156348320
+  version_requirements: *2156895880
 - !ruby/object:Gem::Dependency
   name: tilt
-  requirement: &2156347220 !ruby/object:Gem::Requirement
+  requirement: &2156895460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2156347220
+  version_requirements: *2156895460
 description: Reacco makes your readme's pretty.
 email:
 - rico@sinefunc.com