Class: Detroit::RDoc

Inherits:
Tool
  • Object
show all
Includes:
Standard
Defined in:
lib/detroit-rdoc.rb

Overview

RDoc documentation tool generates RDocs for Ruby project.

By default it generates the rdoc documentaiton at doc/rdoc, unless an ‘rdoc’ directory exists in the project’s root directory, in which case the rdoc documentation will be stored there.

  • document

  • reset

  • clean

  • purge

Constant Summary collapse

MANPAGE =

Location of manpage for tool.

File.dirname(__FILE__) + '/../man/detroit-rdoc.5'
DEFAULT_OUTPUT =

Default location to store rdoc documentation files.

"doc"
DEFAULT_OUTPUT_MATCH =

Locations to check for existance in deciding where to store rdoc documentation.

"{site/rdoc,doc/rdoc,rdoc}"
DEFAULT_MAIN =

Default main file.

"README{,.*}"
DEFAULT_FORMAT =

Default rdoc format to use.

"darkfish"
DEFAULT_EXTRA =

Deafult extra options to add to rdoc call.

''

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#adfile ⇒ Object

Ad file html snippet to add to html rdocs.



92
93
94
 
# File 'lib/detroit-rdoc.rb', line 92

def adfile
  @adfile
end

#exclude ⇒ Object

Paths to specifically exclude.



86
87
88
 
# File 'lib/detroit-rdoc.rb', line 86

def exclude
  @exclude
end

#extra ⇒ Object

Additional options passed to the rdoc command.



95
96
97
 
# File 'lib/detroit-rdoc.rb', line 95

def extra
  @extra
end

#files ⇒ Object

Which files to document.



74
75
76
 
# File 'lib/detroit-rdoc.rb', line 74

def files
  @files
end

#format ⇒ Object

Format to use (defaults to ENV or ‘darkfish’)



65
66
67
 
# File 'lib/detroit-rdoc.rb', line 65

def format
  @format
end

#ignore ⇒ Object

File patterns to ignore.



89
90
91
 
# File 'lib/detroit-rdoc.rb', line 89

def ignore
  @ignore
end

#main ⇒ Object

Main file. This can be a file pattern. (READMEDetroit::RDoc.,,.*)



71
72
73
 
# File 'lib/detroit-rdoc.rb', line 71

def main
  @main
end

#output ⇒ Object

Where to save rdoc files (doc/rdoc).



62
63
64
 
# File 'lib/detroit-rdoc.rb', line 62

def output
  @output
end

#template ⇒ Object

Template to use (defaults to ENV)



68
69
70
 
# File 'lib/detroit-rdoc.rb', line 68

def template
  @template
end

#title ⇒ Object

Title of documents. Defaults to general metadata title field.



59
60
61
 
# File 'lib/detroit-rdoc.rb', line 59

def title
  @title
end

Instance Method Details

#assemble?(station, options = {}) ⇒ Boolean, Symbol

This tool ties into the ‘document`, `reset`, `clean` and `purge` stations of the standard assembly.

Returns:

  • (Boolean, Symbol) 


201
202
203
204
205
206
207
 
# File 'lib/detroit-rdoc.rb', line 201

def assemble?(station, options={})
  return true if station == :document
  return true if station == :reset
  return true if station == :clean
  return true if station == :purge
  return false
end

#clean ⇒ Object

A no-op. RDoc has no residuals to remove.



176
177
 
# File 'lib/detroit-rdoc.rb', line 176

def clean
end

#current? ⇒ Boolean

Are RDocs current and not in need of updating? If yes, returns string message, otherwise ‘false`.

Returns:

  • (Boolean) 


189
190
191
192
193
194
195
 
# File 'lib/detroit-rdoc.rb', line 189

def current?
  if outofdate?(output, *resolved_files)
    return false
  else
    "RDocs are current (#{output})"
  end
end

#document ⇒ Object

Generate Rdoc documentation. Settings are the same as the rdoc command’s option, with two exceptions: inline for inline-source and output for op.



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/detroit-rdoc.rb', line 103

def document
  title    = self.title
  output   = self.output
  main     = self.main
  format   = self.format
  template = self.template
  adfile   = self.adfile
  extra    = self.extra

  # you can specify more than one possibility, first match wins
  adfile = [adfile].flatten.compact.find do |f|
    File.exist?(f)
  end

  main = Dir.glob(main, File::FNM_CASEFOLD).first

  #include_files  = files.to_list.uniq
  #exclude_files  = exclude.to_list.uniq
  #ignore_matches = ignore.to_list.uniq

  #if mfile = project.manifest.file
  #  exclude_files << mfile.basename.to_s # TODO: I think base name should retun a string?
  #end

  #filelist = amass(include_files, exclude_files, ignore_matches)
  #filelist = filelist.select{ |fname| File.file?(fname) }

  if (msg = current?) && !force?
    report msg
  else
    status "Generating #{output}"

    pdir = File.dirname(output)
    mkdir_p(pdir) unless directory?(pdir)

    #target_main = Dir.glob(target['main'].to_s, File::FNM_CASEFOLD).first
    #target_main   = File.expand_path(target_main) if target_main
    #target_output = File.expand_path(File.join(output, subdir))
    #target_output = File.join(output, subdir)

    argv = []
    argv.concat(extra.split(/\s+/))
    argv.concat ['--op', output]
    argv.concat ['--main', main] if main
    argv.concat ['--format', format] if format
    argv.concat ['--template', template] if template
    argv.concat ['--title', title] if title

    #exclude_files = self.exclude.to_list.uniq
    #exclude_files.each do |file|
    #  argv.concat ['--exclude', file]
    #end

    argv = argv + resolved_files

    rdoc_target(output, argv)
    rdoc_insert_ads(output, adfile)

    touch(output)

    output
  end
end

#prerequisite ⇒ Object

NOTE: Due to a bug in RDoc this needs to be done for now so that alternate templates can be used.



47
48
49
50
51
52
53
54
55
56
 
# File 'lib/detroit-rdoc.rb', line 47

def prerequisite
  begin
    require 'rubygems'
    gem('rdoc')
  rescue LoadError
    $stderr.puts "Oh no! No modern rdoc!"
  end
  #require 'rdoc'
  require 'rdoc/rdoc'
end

#purge ⇒ Object

Remove rdoc output.



180
181
182
183
184
185
 
# File 'lib/detroit-rdoc.rb', line 180

def purge
  if directory?(output)
    rm_r(output)
    report "Removed #{output}"
  end
end

#reset ⇒ Object

Reset output directory, marking it as out-of-date.



168
169
170
171
172
173
 
# File 'lib/detroit-rdoc.rb', line 168

def reset
  if directory?(output)
    utime(0, 0, output)
    report "Reset #{output}"
  end
end