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.

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

adfile[RW]

Ad file html snippet to add to html rdocs.

exclude[RW]

Paths to specifically exclude.

extra[RW]

Additional options passed to the rdoc command.

files[R]

Which files to document.

format[RW]

Format to use (defaults to ENV or 'darkfish')

ignore[RW]

File patterns to ignore.

main[RW]

Main file. This can be a file pattern. (README{,.*})

output[RW]

Where to save rdoc files (doc/rdoc).

template[RW]

Template to use (defaults to ENV)

title[RW]

Title of documents. Defaults to general metadata title field.

Public Instance Methods

assemble?(station, options={}) click to toggle source

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
clean() click to toggle source

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

# File lib/detroit-rdoc.rb, line 176
def clean
end
current?() click to toggle source

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
document() click to toggle source

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
files=(list) click to toggle source
# File lib/detroit-rdoc.rb, line 77
def files=(list)
  @resolved_files = nil
  @files = list.to_list
end
prerequisite() click to toggle source

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
purge() click to toggle source

Remove rdoc output.

# File lib/detroit-rdoc.rb, line 180
def purge
  if directory?(output)
    rm_r(output)
    report "Removed #{output}"
  end
end
reset() click to toggle source

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

initialize_defaults() click to toggle source

Setup default attribute values.

Calls superclass method
# 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
rdoc_insert_ads(site, adfile) click to toggle source

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
rdoc_target(output, argv=[]) click to toggle source

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
resolved_files() click to toggle source
# 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