Parent

Syckle::Plugins::RDoc

RDoc documentation plugin generates RDocs for your 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.

This plugin provides the following cycle-phases:

main:document  - generate rdocs
main:reset     - mark rdocs out-of-date
main:clean     - remove rdocs

site:document  - generate rdocs
site:reset     - mark rdocs out-of-date
site:clean     - remove rdocs

RDoc service will be available automatically if the project has a doc/rdoc directory.

Constants

DEFAULT_EXTRA

Deafult extra options to add to rdoc call.

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.

DEFAULT_TEMPLATE

Default rdoc template to use.

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[RW]

Which files to document.

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 or ‘darkfish’)

title[RW]

Title of documents. Defaults to general metadata title field.

Public Instance Methods

clean() click to toggle source

Remove rdocs products.

# File lib/plugins/syckle/rdoc.rb, line 191
def clean
  if File.directory?(output)
    rm_r(output)
    report "removed #{output}" #unless trial?
  end
end
document(options=nil) 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/plugins/syckle/rdoc.rb, line 113
def document(options=nil)
  options ||= {}

  title    = options['title']    || self.title
  output   = options['output']   || self.output
  main     = options['main']     || self.main
  template = options['template'] || self.template
  files    = options['files']    || self.files
  exclude  = options['exclude']  || self.exclude
  adfile   = options['adfile']   || self.adfile
  extra    = options['extra']    || self.extra

  # NOTE: Due to a bug in RDoc this needs to be done for now
  # so that alternate templates can be used.
  begin
    require 'rubygems'
    gem('rdoc')
  rescue LoadError
  end

  require 'rdoc/rdoc'

  # 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

  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)
  filelist = filelist.select{ |fname| File.file?(fname) }

  if outofdate?(output, *filelist) or force?
    status "Generating #{output}"

    #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 ['--template', template] if template
    argv.concat ['--title', title] if title

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

    argv = argv + filelist #include_files

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

    touch(output)
  else
    status "RDocs are current (#{output})"
  end
end
main_document click to toggle source

Generate rdocs in main cycle.

# File lib/plugins/syckle/rdoc.rb, line 28
cycle :main, :document
reset() click to toggle source

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

# File lib/plugins/syckle/rdoc.rb, line 183
def reset
  if File.directory?(output)
    File.utime(0,0,output)
    report "reset #{output}" #unless trial?
  end
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.