Parent

Syckle::Plugins::Yard

Yard documentation plugin generates docs for your project.

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

This plugin provides the following cycle-phases:

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

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

Yard service will be available automatically if the project has a doc/yard directory.

Constants

DEFAULT_EXTRA

Deafult extra options to add to yardoc call.

DEFAULT_OUTPUT

Default location to store yard documentation files.

DEFAULT_OUTPUT_MATCH

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

DEFAULT_README

Default main file.

DEFAULT_TEMPLATE

Default template to use.

Attributes

exclude[RW]

Paths to specifically exclude.

extra[RW]

Additional options passed to the yardoc command.

files[RW]

Which files to document.

output[RW]

Where to save yard files (doc/yard).

readme[RW]

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

template[RW]

Template to use (defaults to ENV or ‘html’)

title[RW]

Title of documents. Defaults to general metadata title field.

Public Instance Methods

clean(options=nil) click to toggle source

Remove yardoc products.

# File lib/plugins/syckle/yard.rb, line 174
def clean(options=nil)
  output = options['output'] || self.output #|| 'doc/yard'

  if File.directory?(output)
    rm_r(output)
    status "Removed #{output}" unless trial?
  end
end
document(options=nil) click to toggle source

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

# File lib/plugins/syckle/yard.rb, line 113
def document(options=nil)
  options ||= {}

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

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

  # YARD SUCKS --THIS DOESN'T WORK ON YARD LINE, WE MUST DO IT OURSELVES!!!
  exclude = exclude.to_list
  exclude = exclude.collect{ |g| Dir.glob(File.join(g, '**/*')) }.flatten

  files = files.to_list
  files = files.map{ |g| Dir.glob(g) }.flatten
  files = files.map{ |f| File.directory?(f) ? File.join(f,'**','*') : f }
  files = files.map{ |g| Dir.glob(g) }.flatten  # need this to remove unwanted toplevel files
  files = files.reject{ |f| File.directory?(f) }

  files = files - Dir.glob('rakefile{,.rb}', File::FNM_CASEFOLD)

  mfile = project.manifest_file
  mfile = project.manifest_file.basename if mfile

  exclude = (exclude + [mfile].compact).uniq

  files = files - [mfile].compact
  files = files - exclude

  input = files.uniq

  if outofdate?(output, *input) 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)

    cmdopts = {}
    cmdopts['output-dir'] = output
    cmdopts['readme']     = readme if readme
    cmdopts['template']   = template
    cmdopts['title']      = title
    #cmdopts['exclude']   = exclude

    yard_target(output, input, cmdopts)
    #rdoc_insert_ads(output, adfile)

    touch(output)
  else
    status "Yardocs are current (#{output})."
  end
end
initialize_defaults() click to toggle source
# File lib/plugins/syckle/yard.rb, line 67
def initialize_defaults
  @title    = metadata.title
  @files    = metadata.loadpath + ['[A-Z]*', 'bin'] # DEFAULT_FILES

  @output   = Dir[DEFAULT_OUTPUT_MATCH].first || DEFAULT_OUTPUT
  @readme   = DEFAULT_README
  @extra    = DEFAULT_EXTRA
  @template = ENV['YARD_TEMPLATE'] || DEFAULT_TEMPLATE
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.