class Detroit::RDoc
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
Constants
- DEFAULT_EXTRA
Deafult extra options to add to rdoc call.
- DEFAULT_FORMAT
Default rdoc format to use.
- DEFAULT_MAIN
Default main file.
- DEFAULT_OUTPUT
Default location to store rdoc documentation files.
- DEFAULT_OUTPUT_MATCH
Locations to check for existance in deciding where to store rdoc documentation.
- MANPAGE
Location of manpage for tool.
Attributes
Ad file html snippet to add to html rdocs.
Paths to specifically exclude.
Additional options passed to the rdoc command.
Which files to document.
Format to use (defaults to ENV or 'darkfish')
File patterns to ignore.
Main file. This can be a file pattern. (README{,.*})
Where to save rdoc files (doc/rdoc).
Template to use (defaults to ENV)
Title of documents. Defaults to general metadata title field.
Public Instance Methods
This tool ties into the `document`, `reset`, `clean` and `purge` stations of the standard assembly.
@return [Boolean,Symbol]
# 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
A no-op. RDoc
has no residuals to remove.
# File lib/detroit-rdoc.rb, line 176 def clean end
Are RDocs current and not in need of updating? If yes, returns string message, otherwise `false`.
# File lib/detroit-rdoc.rb, line 189 def current? if outofdate?(output, *resolved_files) return false else "RDocs are current (#{output})" end end
Generate Rdoc documentation. Settings are the same as the rdoc command's option, with two exceptions: inline
for inline-source
and output
for op
.
# 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
# File lib/detroit-rdoc.rb, line 77 def files=(list) @resolved_files = nil @files = list.to_list end
NOTE: Due to a bug in RDoc
this needs to be done for now so that alternate templates can be used.
# 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
Remove rdoc output.
# File lib/detroit-rdoc.rb, line 180 def purge if directory?(output) rm_r(output) report "Removed #{output}" end end
Reset output directory, marking it as out-of-date.
# File lib/detroit-rdoc.rb, line 168 def reset if directory?(output) utime(0, 0, output) report "Reset #{output}" end end
Private Instance Methods
Setup default attribute values.
# File lib/detroit-rdoc.rb, line 225 def initialize_defaults super @title = metadata.title @files = metadata.loadpath + ['[A-Z]*', 'bin'] # DEFAULT_FILES @output = Dir[DEFAULT_OUTPUT_MATCH].first || DEFAULT_OUTPUT @extra = DEFAULT_EXTRA @main = Dir[DEFAULT_MAIN].first || 'README' @format = ENV['RDOC_FORMAT'] || DEFAULT_FORMAT @template = ENV['RDOC_TEMPLATE'] end
Insert an ad into rdocs, if exists.
Note that this code is needs work, as is it was designed to work with an old version of RDoc
.
# File lib/detroit-rdoc.rb, line 285 def rdoc_insert_ads(site, adfile) return if trial? return unless adfile && File.file?(adfile) adtext = File.read(adfile) #puts dirs = Dir.glob(File.join(site,'*/')) dirs.each do |dir| files = Dir.glob(File.join(dir, '**/*.html')) files.each do |file| html = File.read(file) bodi = html.index('<body>') next unless bodi html[bodi + 7] = "\n" + adtext File.write(file, html) unless trial? end end end
Generate rdocs for input targets.
# File lib/detroit-rdoc.rb, line 255 def rdoc_target(output, argv=[]) rm_r(output) if exist?(output) and safe?(output) # remove old rdocs #rdocopt['op'] = output #if template == 'hanna' # cmd = "hanna #{extra} " + [input, rdocopt].to_console #else # cmd = "rdoc #{extra} " + [input, rdocopt].to_console #end #argv = ("#{extra}" + [input, rdocopt].to_console).split(/\s+/) if trial? puts "rdoc " + argv.join(" ") else trace "rdoc " + argv.join(" ") #if trace? or verbose? rdoc = ::RDoc::RDoc.new rdoc.document(argv) #silently do # sh(cmd) #shell(cmd) #end end end
# File lib/detroit-rdoc.rb, line 238 def resolved_files @resolved_files ||= ( include_files = self.files.to_list.uniq exclude_files = self.exclude.to_list.uniq ignore_matches = self.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 list = amass(include_files, exclude_files, ignore_matches) list = list.select{ |fname| File.file?(fname) } list ) end