vocco 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/VERSION CHANGED
@@ -1 +1 @@
1
- 0.1.2
1
+ 0.1.3
@@ -1,59 +1,94 @@
1
1
 
2
2
 
3
- require 'hpricot'
4
- require 'tilt'
5
- require 'tempfile'
3
+ # Gem Use
4
+ require 'hpricot' # parse and modify html
5
+ require 'tilt' # generate sidebar html
6
+ require 'tempfile' # temporary vimscript
6
7
 
7
8
 
8
9
  module Vocco
9
10
 
10
- require 'vocco/generator'
11
- require 'vocco/cli'
11
+ # File Responsibility
12
+ require 'vocco/generator' # Generate docs
13
+ require 'vocco/cli' # Command line interface
12
14
 
13
15
  class << self
14
- def name_fallback
15
- gemspec(:name) || File.basename(Dir.pwd)
16
+
17
+ # Vocco::run is the interface for using Vocco as a gem.
18
+ def run(opts)
19
+ validate(opts)
20
+ Generator.new(
21
+ DEFAULTS.merge(opts)
22
+ ).run
16
23
  end
17
24
 
18
- def site_fallback
19
- gemspec(:homepage)
25
+ alias :run! :run
26
+ alias :start :run
27
+
28
+ def validate(opts)
29
+ bad_opts = opts.keys - OPTION_NAMES
30
+
31
+ if bad_opts.any?
32
+ raise "Invalid options: #{bad_opts}"
33
+ end
20
34
  end
21
35
 
36
+ # Tries to read a property from the gemspec with the same name
37
+ # as the working dir, in the working dir.
22
38
  def gemspec(prop)
23
39
  begin
24
40
  require 'rubygems'
25
- @gemspec ||= Gem::Specification.load(File.basename(Dir.pwd) + '.gemspec')
41
+ @gemspec ||= Gem::Specification.load(
42
+ File.basename(Dir.pwd) + '.gemspec')
26
43
  @gemspec.send prop
27
44
  rescue
28
45
  nil
29
46
  end
30
47
  end
48
+ end
31
49
 
32
- def run(opts)
50
+
51
+ # These are the available options. They can be given on
52
+ # the command line, the linux way, or as a hash to
53
+ # Vocco.run(...), the Rubygem way. The format is:
54
+ #
55
+ # [name, description,
56
+ # default_value
57
+ # ]
33
58
 
34
- bad_opts = opts.keys - OPTIONS.map {|line| line[0] }
59
+ OPTIONS = [
60
+ [:files, "File match globs",
61
+ %w{**/*.rb README LICENSE}
62
+ ],
35
63
 
36
- unless bad_opts.empty?
37
- raise "Invalid options: #{bad_opts}"
38
- end
64
+ [:out, "Output directory",
65
+ './docs'
66
+ ],
39
67
 
40
- 0.upto(OPTIONS.size - 1) do |n|
41
- opts[OPTIONS[n][0]] ||= OPTIONS[n][2]
42
- end
68
+ [:notes, "Note directories",
69
+ ['./notes']
70
+ ],
43
71
 
44
- Generator.new(opts).run
45
- end
46
- alias :run! :run
47
- end
72
+ [:name, "Project name",
73
+ gemspec(:name) || File.basename(Dir.pwd)
74
+ ],
48
75
 
49
- OPTIONS = [
50
- [:files, "File match globs", %w{**/*.rb README LICENSE} ],
51
- [:out, "Output directory", './docs' ],
52
- [:notes, "Note directories", ['./notes'] ],
53
- [:name, "Project name", name_fallback ],
54
- [:site, "Project url", site_fallback ],
55
- [:vim, "Vim command", %w{macvim gvim vim} ]
76
+ [:site, "Project url",
77
+ gemspec(:homepage)
78
+ ],
79
+
80
+ [:vim, "Vim command", %w{macvim gvim vim}
81
+ ]
56
82
  ]
83
+
84
+ OPTION_NAMES = OPTIONS.map(&:first)
85
+
86
+ DEFAULTS = {}
87
+
88
+ OPTIONS.each do |opt|
89
+ DEFAULTS[opt[0]] = opt[2]
90
+ end
91
+
57
92
  end
58
93
 
59
94
 
@@ -1,39 +1,40 @@
1
1
 
2
+ require 'fileutils'
3
+
2
4
 
3
5
  class Vocco::Generator
4
6
 
5
- require 'vocco/generator/css'
7
+ # File What
8
+ require 'vocco/generator/css' # CSS additions
9
+ require 'vocco/generator/source_file' # SourceFile class
6
10
 
7
11
  attr_reader :globs, :notes, :out, :name, :site
8
12
 
9
13
  def initialize(opts)
10
- @globs = opts[:files].map {|path| path.sub(/\/$/, '') }
14
+ @globs = Array(opts[:files]
15
+ ).compact.map do |glob|
16
+ glob.gsub(/(^\.\/)|(\/$)/, '')
17
+ end
11
18
  @out = opts[:out]
12
- @notes = opts[:notes]
19
+ @notes = Array(opts[:notes]).compact
13
20
  @name = opts[:name].capitalize
14
21
  @site = opts[:site]
15
- @vim = opts[:vim]
16
- validate_out
17
- end
18
-
19
- def run
20
- run_vim; postprocess
21
- end
22
- alias :run! :run
22
+ @vim = Array(opts[:vim]).compact
23
23
 
24
- def trimmed_globs
25
- @trimmed_globs ||= @globs.map do |glob|
26
- glob.gsub(/(^\.\/)|(\/$)/, '')
27
- end
24
+ FileUtils.mkdir_p(@out) # ensure out dir exists
28
25
  end
29
26
 
27
+ # the paths underneath which the @globs are globbing;
28
+ # the static part of the glob, or "scope" of sorts
30
29
  def scopes
31
- @scopes ||= trimmed_globs.map do |glob|
30
+ @scopes ||= @globs.map do |glob|
32
31
  tokens = glob.split('*')
33
32
  tokens.size > 1 ? tokens.first : nil
34
33
  end.compact
35
34
  end
36
35
 
36
+ # regex to trim the glob dir scopes off a source
37
+ # file path.
37
38
  def glob_regex
38
39
  @glob_regex ||= begin
39
40
  str = scopes.map do |scope|
@@ -43,13 +44,7 @@ class Vocco::Generator
43
44
  end
44
45
  end
45
46
 
46
- def doc_regex
47
- @doc_regex ||= begin
48
- str = Regexp::escape(@out) + '/'
49
- /^#{str}/
50
- end
51
- end
52
-
47
+ # array of SourceFile's mapped from the glob matches
53
48
  def files
54
49
  @files ||= @globs.map do |glob|
55
50
  Dir[glob]
@@ -58,13 +53,12 @@ class Vocco::Generator
58
53
  end
59
54
  end
60
55
 
61
- private
56
+ def run
57
+ run_vim; postprocess
58
+ end
59
+ alias :run! :run
62
60
 
63
- def validate_out
64
- unless File.directory?(@out)
65
- raise "#{@out} is not a valid directory."
66
- end
67
- end
61
+ private
68
62
 
69
63
  def run_vim
70
64
  script = Tempfile.new('vimdocco')
@@ -112,69 +106,3 @@ class Vocco::Generator
112
106
  end
113
107
  end
114
108
 
115
- class Vocco::Generator::SourceFile
116
- require 'vocco/generator/source_file/html_template'
117
-
118
- def initialize(file, generator)
119
- @file = file
120
- @gen = generator
121
- end
122
-
123
- attr_reader :file
124
-
125
- def short_path
126
- @short_path ||= @file.sub(@gen.glob_regex, '')
127
- end
128
-
129
- def short_dirname
130
- File.dirname(short_path).sub(/^\.\//, '')
131
- end
132
-
133
- def dirname
134
- File.dirname(@file)
135
- end
136
-
137
- def basename
138
- File.basename(@file)
139
- end
140
-
141
- def doc_prefix
142
- short_dirname == '.' ? '' : short_dirname.gsub('/', '-') + '-'
143
- end
144
-
145
- def doc_path
146
- File.join(@gen.out, doc_prefix + basename + '.html')
147
- end
148
-
149
- def doc_link
150
- './' + doc_path.sub(@gen.doc_regex, '')
151
- end
152
-
153
- def notes
154
- rendered = render_notes
155
- rendered.any? ?
156
- rendered.join("\n") : nil
157
- end
158
-
159
- def render_notes
160
- Dir[note_glob].map do |path|
161
- Tilt.new(path).render
162
- end
163
- end
164
-
165
- def note_glob
166
- dirs = [dirname]
167
- @gen.notes.each do |dir|
168
- dirs << File.join(dir, short_dirname)
169
- end
170
- ext = '.{textile,md,mkd,markdown,rdoc}'
171
- dir_glob = '{' + dirs.join(',') + '}/'
172
- dir_glob + basename + ext
173
- end
174
-
175
- class_eval <<-EOF, '(template)'
176
- def render_template
177
- #{HTML_TEMPLATE}
178
- end
179
- EOF
180
- end
@@ -0,0 +1,81 @@
1
+
2
+
3
+
4
+ class Vocco::Generator::SourceFile
5
+ require 'vocco/generator/source_file/html_template'
6
+
7
+ NOTE_FORMATS = '.{textile,md,mkd,markdown,rdoc}'
8
+
9
+ def initialize(file, generator)
10
+ @file = file
11
+ @gen = generator
12
+ end
13
+
14
+ attr_reader :file # full file path
15
+
16
+ # full dirname
17
+ def dirname
18
+ File.dirname(@file)
19
+ end
20
+
21
+ def basename
22
+ File.basename(@file)
23
+ end
24
+
25
+ # file path with glob dir scope trimmed off
26
+ def short_path
27
+ @short_path ||= @file.sub(@gen.glob_regex, '')
28
+ end
29
+
30
+ # dirname of the above
31
+ def short_dirname
32
+ File.dirname(short_path).sub(/^\.\//, '')
33
+ end
34
+
35
+ # corresponding doc file basename
36
+ def doc_basename
37
+ doc_scope + basename + '.html'
38
+ end
39
+
40
+ # corresponding doc file path
41
+ def doc_path
42
+ File.join(@gen.out, doc_basename)
43
+ end
44
+
45
+ # relative link to doc
46
+ def doc_link
47
+ './' + doc_basename
48
+ end
49
+
50
+ def notes
51
+ @notes ||= Dir[note_glob].map do |path|
52
+ Tilt.new(path).render
53
+ end
54
+ end
55
+
56
+ # make a method for the html template
57
+ class_eval <<-EOF, '(template)'
58
+ def render_template
59
+ #{HTML_TEMPLATE}
60
+ end
61
+ EOF
62
+
63
+ private
64
+ # doc filename prefix based on source file folder
65
+ def doc_scope
66
+ short_dirname == '.' ? '' : short_dirname.gsub('/', '-') + '-'
67
+ end
68
+
69
+ # the dirs in which to look for notes concerning this file.
70
+ def note_dirs
71
+ @gen.notes.inject([dirname]) do |dirs, dir|
72
+ dirs << File.join(dir, short_dirname)
73
+ end
74
+ end
75
+
76
+ # glob matching notes concerning this file
77
+ def note_glob
78
+ '{' + note_dirs.join(',') + '}/' + basename + NOTE_FORMATS
79
+ end
80
+ end
81
+
@@ -18,10 +18,12 @@ _buf = [] ; _temple_pre_tags = /<pre|<textarea/ ; _buf << ("<div class=\"nav\"><
18
18
  "<a href=\"#{file.doc_link}\">#{file.basename}"\
19
19
  "</a><br>"\
20
20
  ""\
21
- "") ; end ; _buf << ("</p>") ; end ; _buf << ("</div>") ; if notes ;
22
- ; _buf << ("<div class=\"notes area\">#{notes}"\
23
- ""\
24
- "</div>") ; end ; _buf << ("<div class=\"area\"><table><tr><th>Generated:</th><td>"\
21
+ "") ; end ; _buf << ("</p>") ; end ; _buf << ("</div>") ; if notes.any? ;
22
+ ; _buf << ("<div class=\"notes area\">") ;
23
+ ; notes.each do |note| ;
24
+ ; _buf << (note) ;
25
+ ;
26
+ ; end ; _buf << ("</div>") ; end ; _buf << ("<div class=\"area\"><table><tr><th>Generated:</th><td>"\
25
27
  ""\
26
28
  ""\
27
29
  ""\
@@ -6,4 +6,6 @@ These paragraphs are actually "notes" attached to the README -- they were automa
6
6
 
7
7
  The supported note format extensions are: md, mkd, markdown, textile and rdoc.
8
8
 
9
- Have a great day. &hearts;
9
+ Browse around the source code if you like -- mouse over the header just above this text to see a file list.
10
+
11
+ &hearts;
@@ -0,0 +1,9 @@
1
+
2
+
3
+ *Easier to read from the bottom and up.*
4
+
5
+ Responsibilities:
6
+
7
+ * Define Vocco module and require dependencies
8
+ * Define options and defaults
9
+ * Expose interface for usage as Rubygem
@@ -0,0 +1,2 @@
1
+
2
+ Vocco command line interface. Parses command line arguments and runs Vocco.
@@ -0,0 +1,13 @@
1
+
2
+
3
+ The Vocco doc generator.
4
+
5
+ Responsibilities:
6
+
7
+ * Normalize options
8
+ * Make a vimscript to produce the docs
9
+ * Run Vim
10
+ * Postprocess the generated docs, adding:
11
+ * CSS
12
+ * File index
13
+ * Notes
@@ -0,0 +1,4 @@
1
+
2
+ Compiled CSS.
3
+
4
+ The original templates live in the `template/` dir, and can be rendered by running `rake build:templates`
@@ -0,0 +1,7 @@
1
+
2
+ Represents a singe source file, matched by the user given globs.
3
+
4
+ Responsibilities:
5
+
6
+ * Manage nasty path stuff
7
+ * Render template, including notes and index
@@ -0,0 +1,4 @@
1
+
2
+ Precompiled template code.
3
+
4
+ The original templates live in the `template/` dir, and can be rendered by running `rake build:templates`
@@ -17,8 +17,10 @@
17
17
  a href="#{file.doc_link}" = file.basename
18
18
  br
19
19
 
20
- - if notes
21
- .notes.area = notes
20
+ - if notes.any?
21
+ .notes.area
22
+ - notes.each do |note|
23
+ = note
22
24
 
23
25
  .area
24
26
  table
@@ -5,11 +5,11 @@
5
5
 
6
6
  Gem::Specification.new do |s|
7
7
  s.name = %q{vocco}
8
- s.version = "0.1.2"
8
+ s.version = "0.1.3"
9
9
 
10
10
  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
11
11
  s.authors = ["jbe"]
12
- s.date = %q{2011-03-03}
12
+ s.date = %q{2011-03-04}
13
13
  s.default_executable = %q{vocco}
14
14
  s.description = %q{vocco is an extra super quick-and-dirty documentation generator based on Vim, written in Ruby.}
15
15
  s.email = %q{post@jostein.be}
@@ -33,8 +33,15 @@ Gem::Specification.new do |s|
33
33
  "lib/vocco/cli.rb",
34
34
  "lib/vocco/generator.rb",
35
35
  "lib/vocco/generator/css.rb",
36
+ "lib/vocco/generator/source_file.rb",
36
37
  "lib/vocco/generator/source_file/html_template.rb",
37
38
  "notes/README.md",
39
+ "notes/vocco.rb.md",
40
+ "notes/vocco/cli.rb.md",
41
+ "notes/vocco/generator.rb.md",
42
+ "notes/vocco/generator/css.rb.md",
43
+ "notes/vocco/generator/source_file.rb.md",
44
+ "notes/vocco/generator/source_file/html_template.rb.md",
38
45
  "template/css.sass",
39
46
  "template/html.slim",
40
47
  "vocco.gemspec"
metadata CHANGED
@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
5
5
  segments:
6
6
  - 0
7
7
  - 1
8
- - 2
9
- version: 0.1.2
8
+ - 3
9
+ version: 0.1.3
10
10
  platform: ruby
11
11
  authors:
12
12
  - jbe
@@ -14,7 +14,7 @@ autorequire:
14
14
  bindir: bin
15
15
  cert_chain: []
16
16
 
17
- date: 2011-03-03 00:00:00 +01:00
17
+ date: 2011-03-04 00:00:00 +01:00
18
18
  default_executable: vocco
19
19
  dependencies:
20
20
  - !ruby/object:Gem::Dependency
@@ -184,8 +184,15 @@ files:
184
184
  - lib/vocco/cli.rb
185
185
  - lib/vocco/generator.rb
186
186
  - lib/vocco/generator/css.rb
187
+ - lib/vocco/generator/source_file.rb
187
188
  - lib/vocco/generator/source_file/html_template.rb
188
189
  - notes/README.md
190
+ - notes/vocco.rb.md
191
+ - notes/vocco/cli.rb.md
192
+ - notes/vocco/generator.rb.md
193
+ - notes/vocco/generator/css.rb.md
194
+ - notes/vocco/generator/source_file.rb.md
195
+ - notes/vocco/generator/source_file/html_template.rb.md
189
196
  - template/css.sass
190
197
  - template/html.slim
191
198
  - vocco.gemspec