rocco 0.2 → 0.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/Rakefile CHANGED
@@ -22,7 +22,7 @@ end
22
22
 
23
23
  # Bring in Rocco tasks
24
24
  require 'rocco/tasks'
25
- Rocco::make 'docs/'
25
+ Rocco::make 'docs/', FileList['lib/**/*.rb', 'bin/rocco']
26
26
 
27
27
  desc 'Build rocco docs'
28
28
  task :docs => :rocco
data/bin/rocco CHANGED
@@ -1,6 +1,54 @@
1
1
  #!/usr/bin/env ruby
2
- libdir = File.expand_path('../../lib', __FILE__).sub(/^#{Dir.pwd}\//, '')
2
+ # The `rocco(1)` executable.
3
+ #
4
+ # This isn't documented yet.
5
+ #
6
+ #/ Usage: rocco [-o <dir>] <file>...
7
+ #/ Generate literate-programming-style documentation for Ruby source <file>s.
8
+ #/
9
+ #/ Options:
10
+ #/ -o, --output=<dir> Directory where generated HTML files are written
11
+ #/
12
+ #/ --help Show this help message
13
+
14
+ require 'optparse'
15
+
16
+ # Write usage message to stdout and exit.
17
+ def usage(stream=$stderr, status=1)
18
+ stream.puts File.read(__FILE__).
19
+ grep(/^#\//).
20
+ map { |line| line.sub(/^#. ?/, '') }.
21
+ join
22
+ exit status
23
+ end
24
+
25
+ # Like `Kernel#abort` but writes a note encouraging the user to consult
26
+ # `rocco --help` for more information.
27
+ def abort_with_note(message=nil)
28
+ $stderr.puts message if message
29
+ abort "See `rocco --help' for usage information."
30
+ end
3
31
 
32
+ # Parse command line options, aborting if anything goes wrong.
33
+ output_dir = '.'
34
+ sources = []
35
+ ARGV.options { |o|
36
+ o.program_name = File.basename($0)
37
+ o.on("-o", "--output=DIR") { |dir| output_dir = dir }
38
+ o.on_tail("-h", "--help") { usage($stdout, 0) }
39
+ o.parse!
40
+ } or abort_with_note
41
+
42
+ # Eat sources from ARGV.
43
+ sources << ARGV.shift while ARGV.any?
44
+
45
+ # Make sure we have some files to work with.
46
+ if sources.empty?
47
+ abort_with_note "#{File.basename($0)}: no input <file>s given"
48
+ end
49
+
50
+ # What a fucking mess. Most of this is duplicated in rocco.rb too.
51
+ libdir = File.expand_path('../../lib', __FILE__).sub(/^#{Dir.pwd}\//, '')
4
52
  begin
5
53
  require 'rdiscount'
6
54
  require 'rocco'
@@ -27,9 +75,13 @@ rescue LoadError
27
75
  raise
28
76
  end
29
77
 
30
- ARGV.each do |filename|
31
- rocco = Rocco.new(filename)
32
- dest = File.basename(filename, '.rb') + '.html'
33
- warn "rocco: #{filename} -> #{dest}"
78
+ # Create the output directory if it doesn't already exist.
79
+ Dir.mkdir output_dir if !File.directory?(output_dir)
80
+
81
+ # Run each file through Rocco and write output.
82
+ sources.each do |filename|
83
+ rocco = Rocco.new(filename, sources)
84
+ dest = File.join(output_dir, File.basename(filename, '.rb') + '.html')
85
+ puts "rocco: #{filename} -> #{dest}"
34
86
  File.open(dest, 'wb') { |fd| fd.write(rocco.to_html) }
35
87
  end
@@ -56,14 +56,14 @@ end
56
56
 
57
57
  #### Public Interface
58
58
 
59
- # `Rocco.new` takes a source `filename` and an optional `block`.
60
- # When `block` is given, it must read the contents of the file using
61
- # whatever means necessary and return it as a string. With no `block`, the
62
- # file is read to retrieve data.
59
+ # `Rocco.new` takes a source `filename`, an optional list of source filenames
60
+ # for other documentation sources, and an optional `block`. When `block` is
61
+ # given, it must read the contents of the file using whatever means necessary
62
+ # and return it as a string. With no `block`, the file is read to retrieve data.
63
63
  class Rocco
64
- VERSION = '0.2'
64
+ VERSION = '0.3'
65
65
 
66
- def initialize(filename, &block)
66
+ def initialize(filename, sources=[], &block)
67
67
  @file = filename
68
68
  @data =
69
69
  if block_given?
@@ -71,6 +71,7 @@ class Rocco
71
71
  else
72
72
  File.read(filename)
73
73
  end
74
+ @sources = sources
74
75
  @sections = highlight(split(parse(@data)))
75
76
  end
76
77
 
@@ -83,6 +84,10 @@ class Rocco
83
84
  # respectively.
84
85
  attr_reader :sections
85
86
 
87
+ # A list of all source filenames included in the documentation set. Useful
88
+ # for building an index of other files.
89
+ attr_reader :sources
90
+
86
91
  # Generate HTML output for the entire document.
87
92
  require 'rocco/layout'
88
93
  def to_html
@@ -99,7 +104,7 @@ class Rocco
99
104
  docs, code = [], []
100
105
  data.split("\n").each do |line|
101
106
  case line
102
- when /^\s*#/
107
+ when /^\s*#(?:\s+|$)/
103
108
  if code.any?
104
109
  sections << [docs, code]
105
110
  docs, code = [], []
@@ -8,6 +8,18 @@
8
8
  <body>
9
9
  <div id='container'>
10
10
  <div id="background"></div>
11
+ {{#sources?}}
12
+ <div id="jump_to">
13
+ Jump To &hellip;
14
+ <div id="jump_wrapper">
15
+ <div id="jump_page">
16
+ {{#sources}}
17
+ <a class="source" href="{{ url }}">{{ basename }}</a>
18
+ {{/sources}}
19
+ </div>
20
+ </div>
21
+ </div>
22
+ {{/sources?}}
11
23
  <table cellspacing=0 cellpadding=0>
12
24
  <thead>
13
25
  <tr>
@@ -21,4 +21,18 @@ class Rocco::Layout < Mustache
21
21
  }
22
22
  end
23
23
  end
24
+
25
+ def sources?
26
+ @doc.sources.length > 1
27
+ end
28
+
29
+ def sources
30
+ @doc.sources.sort.map do |source|
31
+ {
32
+ :path => source,
33
+ :basename => File.basename(source),
34
+ :url => File.basename(source, '.rb') + '.html'
35
+ }
36
+ end
37
+ end
24
38
  end
@@ -92,7 +92,7 @@ class Rocco
92
92
  prerequisites = [@dest, source_file] + rocco_source_files
93
93
  file dest_file => prerequisites do |f|
94
94
  verbose { puts "rocco: #{source_file} -> #{dest_file}" }
95
- rocco = Rocco.new(source_file)
95
+ rocco = Rocco.new(source_file, @sources.to_a)
96
96
  File.open(dest_file, 'wb') { |fd| fd.write(rocco.to_html) }
97
97
  end
98
98
  task @name => dest_file
@@ -3,8 +3,8 @@ Gem::Specification.new do |s|
3
3
  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
4
4
 
5
5
  s.name = 'rocco'
6
- s.version = '0.2'
7
- s.date = '2010-03-11'
6
+ s.version = '0.3'
7
+ s.date = '2010-03-16'
8
8
 
9
9
  s.description = "Docco in Ruby"
10
10
  s.summary = s.description
metadata CHANGED
@@ -4,8 +4,8 @@ version: !ruby/object:Gem::Version
4
4
  prerelease: false
5
5
  segments:
6
6
  - 0
7
- - 2
8
- version: "0.2"
7
+ - 3
8
+ version: "0.3"
9
9
  platform: ruby
10
10
  authors:
11
11
  - Ryan Tomayko
@@ -13,7 +13,7 @@ autorequire:
13
13
  bindir: bin
14
14
  cert_chain: []
15
15
 
16
- date: 2010-03-11 00:00:00 -08:00
16
+ date: 2010-03-16 00:00:00 -07:00
17
17
  default_executable:
18
18
  dependencies:
19
19
  - !ruby/object:Gem::Dependency