vocco 0.1.2 → 0.1.3

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.1.3

data/lib/vocco.rb

@@ -1,59 +1,94 @@
 
 
-require 'hpricot'
-require 'tilt'
-require 'tempfile'
+#        Gem          Use
+require 'hpricot'   # parse and modify html
+require 'tilt'      # generate sidebar html
+require 'tempfile'  # temporary vimscript
 
 
 module Vocco
 
-  require 'vocco/generator'
-  require 'vocco/cli'
+  #        File               Responsibility
+  require 'vocco/generator' # Generate docs
+  require 'vocco/cli'       # Command line interface
 
   class << self
-    def name_fallback
-      gemspec(:name) || File.basename(Dir.pwd)
+
+    # Vocco::run is the interface for using Vocco as a gem.
+    def run(opts)
+      validate(opts)
+      Generator.new(
+        DEFAULTS.merge(opts)
+        ).run
     end
 
-    def site_fallback
-      gemspec(:homepage)
+    alias :run! :run
+    alias :start :run
+
+    def validate(opts)
+      bad_opts = opts.keys - OPTION_NAMES
+
+      if bad_opts.any?
+        raise "Invalid options: #{bad_opts}"
+      end
     end
 
+    # Tries to read a property from the gemspec with the same name
+    # as the working dir, in the working dir.
     def gemspec(prop)
       begin
         require 'rubygems'
-        @gemspec ||= Gem::Specification.load(File.basename(Dir.pwd) + '.gemspec')
+        @gemspec ||= Gem::Specification.load(
+            File.basename(Dir.pwd) + '.gemspec')
         @gemspec.send prop
       rescue
         nil
       end
     end
+  end
 
-    def run(opts)
+  
+  # These are the available options. They can be given on
+  # the command line, the linux way, or as a hash to
+  # Vocco.run(...), the Rubygem way. The format is:
+  #
+  # [name,    description,
+  #           default_value
+  #   ]
 
-      bad_opts = opts.keys - OPTIONS.map {|line| line[0] }
+  OPTIONS = [
+    [:files,  "File match globs",
+              %w{**/*.rb README LICENSE}
+      ],
 
-      unless bad_opts.empty?
-        raise "Invalid options: #{bad_opts}"
-      end
+    [:out,    "Output directory",
+              './docs'
+      ],
 
-      0.upto(OPTIONS.size - 1) do |n|
-        opts[OPTIONS[n][0]] ||= OPTIONS[n][2]
-      end
+    [:notes,  "Note directories",
+              ['./notes']
+      ],
 
-      Generator.new(opts).run
-    end
-    alias :run! :run
-  end
+    [:name,   "Project name",
+              gemspec(:name) || File.basename(Dir.pwd)
+      ],
 
-  OPTIONS = [
-    [:files,  "File match globs",   %w{**/*.rb README LICENSE}  ],
-    [:out,    "Output directory",   './docs'                    ],
-    [:notes,  "Note directories",   ['./notes']                 ],
-    [:name,   "Project name",       name_fallback               ],
-    [:site,   "Project url",        site_fallback               ],
-    [:vim,    "Vim command",        %w{macvim gvim vim}         ]
+    [:site,   "Project url",
+              gemspec(:homepage)
+      ],
+
+    [:vim,    "Vim command", %w{macvim gvim vim}
+      ]
   ]
+
+  OPTION_NAMES  = OPTIONS.map(&:first)
+
+  DEFAULTS      = {}
+  
+  OPTIONS.each do |opt|
+    DEFAULTS[opt[0]] = opt[2]
+  end
+
 end
 
 

data/lib/vocco/generator.rb

@@ -1,39 +1,40 @@
 
+require 'fileutils'
+
 
 class Vocco::Generator
 
-  require 'vocco/generator/css'
+  #        File                           What
+  require 'vocco/generator/css'         # CSS additions
+  require 'vocco/generator/source_file' # SourceFile class
 
   attr_reader :globs, :notes, :out, :name, :site
 
   def initialize(opts)
-    @globs  = opts[:files].map {|path| path.sub(/\/$/, '') }
+    @globs  = Array(opts[:files]
+              ).compact.map do |glob|
+                glob.gsub(/(^\.\/)|(\/$)/, '')
+              end
     @out    = opts[:out]
-    @notes  = opts[:notes]
+    @notes  = Array(opts[:notes]).compact
     @name   = opts[:name].capitalize
     @site   = opts[:site]
-    @vim    = opts[:vim]
-    validate_out
-  end
-
-  def run
-    run_vim; postprocess
-  end
-  alias :run! :run
+    @vim    = Array(opts[:vim]).compact
 
-  def trimmed_globs
-    @trimmed_globs ||= @globs.map do |glob|
-      glob.gsub(/(^\.\/)|(\/$)/, '')
-    end
+    FileUtils.mkdir_p(@out) # ensure out dir exists
   end
 
+  # the paths underneath which the @globs are globbing;
+  # the static part of the glob, or "scope" of sorts
   def scopes
-    @scopes ||= trimmed_globs.map do |glob|
+    @scopes ||= @globs.map do |glob|
       tokens = glob.split('*')
       tokens.size > 1 ? tokens.first : nil
     end.compact
   end
 
+  # regex to trim the glob dir scopes off a source
+  # file path.
   def glob_regex
     @glob_regex ||= begin
       str = scopes.map do |scope|
@@ -43,13 +44,7 @@ class Vocco::Generator
     end
   end
 
-  def doc_regex
-    @doc_regex ||= begin
-      str = Regexp::escape(@out) + '/'
-      /^#{str}/
-    end
-  end
-
+  # array of SourceFile's mapped from the glob matches
   def files
     @files ||= @globs.map do |glob|
       Dir[glob]
@@ -58,13 +53,12 @@ class Vocco::Generator
     end
   end
 
-  private
+  def run
+    run_vim; postprocess
+  end
+  alias :run! :run
 
-    def validate_out
-      unless File.directory?(@out)
-        raise "#{@out} is not a valid directory."
-      end
-    end
+  private
 
     def run_vim
       script = Tempfile.new('vimdocco')
@@ -112,69 +106,3 @@ class Vocco::Generator
     end
 end
 
-class Vocco::Generator::SourceFile
-  require 'vocco/generator/source_file/html_template'
-
-  def initialize(file, generator)
-    @file       = file
-    @gen        = generator
-  end
-
-  attr_reader :file
-
-  def short_path
-    @short_path ||= @file.sub(@gen.glob_regex, '')
-  end
-
-  def short_dirname
-    File.dirname(short_path).sub(/^\.\//, '')
-  end
-
-  def dirname
-    File.dirname(@file)
-  end
-
-  def basename
-    File.basename(@file)
-  end
-
-  def doc_prefix
-    short_dirname == '.' ? '' : short_dirname.gsub('/', '-') + '-'
-  end
-
-  def doc_path
-    File.join(@gen.out, doc_prefix + basename + '.html')
-  end
-
-  def doc_link
-    './' + doc_path.sub(@gen.doc_regex, '')
-  end
-
-  def notes
-    rendered = render_notes
-    rendered.any? ?
-      rendered.join("\n") : nil
-  end
-
-  def render_notes
-    Dir[note_glob].map do |path|
-      Tilt.new(path).render
-    end
-  end
-
-  def note_glob
-    dirs = [dirname]
-    @gen.notes.each do |dir|
-      dirs << File.join(dir, short_dirname)
-    end
-    ext       = '.{textile,md,mkd,markdown,rdoc}'
-    dir_glob  = '{' + dirs.join(',') + '}/'
-    dir_glob + basename + ext
-  end
-
-  class_eval <<-EOF, '(template)'
-    def render_template
-      #{HTML_TEMPLATE}
-    end
-  EOF
-end

data/lib/vocco/generator/source_file.rb

@@ -0,0 +1,81 @@
+
+
+
+class Vocco::Generator::SourceFile
+  require 'vocco/generator/source_file/html_template'
+
+  NOTE_FORMATS = '.{textile,md,mkd,markdown,rdoc}'
+
+  def initialize(file, generator)
+    @file       = file
+    @gen        = generator
+  end
+
+  attr_reader :file # full file path
+
+  # full dirname
+  def dirname
+    File.dirname(@file)
+  end
+
+  def basename
+    File.basename(@file)
+  end
+
+  # file path with glob dir scope trimmed off
+  def short_path
+    @short_path ||= @file.sub(@gen.glob_regex, '')
+  end
+
+  # dirname of the above
+  def short_dirname
+    File.dirname(short_path).sub(/^\.\//, '')
+  end
+
+  # corresponding doc file basename
+  def doc_basename
+    doc_scope + basename + '.html'
+  end
+
+  # corresponding doc file path
+  def doc_path
+    File.join(@gen.out, doc_basename)
+  end
+
+  # relative link to doc
+  def doc_link
+    './' + doc_basename
+  end
+
+  def notes
+    @notes ||= Dir[note_glob].map do |path|
+      Tilt.new(path).render
+    end
+  end
+
+  # make a method for the html template
+  class_eval <<-EOF, '(template)'
+    def render_template
+      #{HTML_TEMPLATE}
+    end
+  EOF
+
+  private
+    # doc filename prefix based on source file folder
+    def doc_scope
+      short_dirname == '.' ? '' : short_dirname.gsub('/', '-') + '-'
+    end
+
+    # the dirs in which to look for notes concerning this file.
+    def note_dirs
+      @gen.notes.inject([dirname]) do |dirs, dir|
+        dirs << File.join(dir, short_dirname)
+      end
+    end
+
+    # glob matching notes concerning this file
+    def note_glob
+      '{' + note_dirs.join(',') + '}/' + basename + NOTE_FORMATS
+    end
+end
+

data/lib/vocco/generator/source_file/html_template.rb

@@ -18,10 +18,12 @@ _buf = [] ; _temple_pre_tags = /<pre|<textarea/ ; _buf << ("<div class=\"nav\"><
 "<a href=\"#{file.doc_link}\">#{file.basename}"\
 "</a><br>"\
 ""\
-"") ; end ; _buf << ("</p>") ; end ; _buf << ("</div>") ; if notes ; 
- ; _buf << ("<div class=\"notes area\">#{notes}"\
-""\
-"</div>") ; end ; _buf << ("<div class=\"area\"><table><tr><th>Generated:</th><td>"\
+"") ; end ; _buf << ("</p>") ; end ; _buf << ("</div>") ; if notes.any? ; 
+ ; _buf << ("<div class=\"notes area\">") ; 
+ ; notes.each do |note| ; 
+ ; _buf << (note) ; 
+ ; 
+ ; end ; _buf << ("</div>") ; end ; _buf << ("<div class=\"area\"><table><tr><th>Generated:</th><td>"\
 ""\
 ""\
 ""\

data/notes/README.md

@@ -6,4 +6,6 @@ These paragraphs are actually "notes" attached to the README -- they were automa
 
 The supported note format extensions are: md, mkd, markdown, textile and rdoc.
 
-Have a great day. ♥
+Browse around the source code if you like -- mouse over the header just above this text to see a file list.
+
+♥

data/notes/vocco.rb.md

@@ -0,0 +1,9 @@
+
+
+*Easier to read from the bottom and up.*
+
+Responsibilities:
+
+* Define Vocco module and require dependencies
+* Define options and defaults
+* Expose interface for usage as Rubygem

data/notes/vocco/cli.rb.md

@@ -0,0 +1,2 @@
+
+Vocco command line interface. Parses command line arguments and runs Vocco.

data/notes/vocco/generator.rb.md

@@ -0,0 +1,13 @@
+
+
+The Vocco doc generator.
+
+Responsibilities:
+
+* Normalize options
+* Make a vimscript to produce the docs
+* Run Vim
+* Postprocess the generated docs, adding:
+  * CSS
+  * File index
+  * Notes

data/notes/vocco/generator/css.rb.md

@@ -0,0 +1,4 @@
+
+Compiled CSS.
+
+The original templates live in the `template/` dir, and can be rendered by running `rake build:templates`

data/notes/vocco/generator/source_file.rb.md

@@ -0,0 +1,7 @@
+
+Represents a singe source file, matched by the user given globs.
+
+Responsibilities:
+
+* Manage nasty path stuff
+* Render template, including notes and index

data/notes/vocco/generator/source_file/html_template.rb.md

@@ -0,0 +1,4 @@
+
+Precompiled template code.
+
+The original templates live in the `template/` dir, and can be rendered by running `rake build:templates`

data/template/html.slim

@@ -17,8 +17,10 @@
             a href="#{file.doc_link}" = file.basename
             br
     
-    - if notes
-      .notes.area = notes
+    - if notes.any?
+      .notes.area
+        - notes.each do |note|
+          = note
 
     .area
       table

data/vocco.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{vocco}
-  s.version = "0.1.2"
+  s.version = "0.1.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["jbe"]
-  s.date = %q{2011-03-03}
+  s.date = %q{2011-03-04}
   s.default_executable = %q{vocco}
   s.description = %q{vocco is an extra super quick-and-dirty documentation generator based on Vim, written in Ruby.}
   s.email = %q{post@jostein.be}
@@ -33,8 +33,15 @@ Gem::Specification.new do |s|
     "lib/vocco/cli.rb",
     "lib/vocco/generator.rb",
     "lib/vocco/generator/css.rb",
+    "lib/vocco/generator/source_file.rb",
     "lib/vocco/generator/source_file/html_template.rb",
     "notes/README.md",
+    "notes/vocco.rb.md",
+    "notes/vocco/cli.rb.md",
+    "notes/vocco/generator.rb.md",
+    "notes/vocco/generator/css.rb.md",
+    "notes/vocco/generator/source_file.rb.md",
+    "notes/vocco/generator/source_file/html_template.rb.md",
     "template/css.sass",
     "template/html.slim",
     "vocco.gemspec"

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 1
-  - 2
-  version: 0.1.2
+  - 3
+  version: 0.1.3
 platform: ruby
 authors: 
 - jbe
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-03 00:00:00 +01:00
+date: 2011-03-04 00:00:00 +01:00
 default_executable: vocco
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -184,8 +184,15 @@ files:
 - lib/vocco/cli.rb
 - lib/vocco/generator.rb
 - lib/vocco/generator/css.rb
+- lib/vocco/generator/source_file.rb
 - lib/vocco/generator/source_file/html_template.rb
 - notes/README.md
+- notes/vocco.rb.md
+- notes/vocco/cli.rb.md
+- notes/vocco/generator.rb.md
+- notes/vocco/generator/css.rb.md
+- notes/vocco/generator/source_file.rb.md
+- notes/vocco/generator/source_file/html_template.rb.md
 - template/css.sass
 - template/html.slim
 - vocco.gemspec