class Detroit::Yard

Yard documentation tool generates YARD documentation for a project.

By default it places the documentaiton file in the standard `doc` directory unless a `site/yard` or `yard` directory exists, in which case the documentation will be stored there.

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.

LOCAL_SETTINGS

Attributes

exclude[RW]

Paths to specifically exclude.

extra[RW]

Additional options passed to the yardoc command.

files[R]

Which library files to document.

ignore[RW]

File patterns to ignore.

output[RW]

Directory in which to save yard files.

readme[RW]

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

template[RW]

Template to use (defaults to ENV or 'default')

title[RW]

Title of documents. Defaults to general metadata title field.

topfiles[R]

Which project top-files to document.

yardopts[RW]

If set to true, use `.yardopts` file and ignore other settings.

Public Class Methods

man_page() click to toggle source
# File lib/detroit-yard.rb, line 266
def self.man_page
  File.dirname(__FILE__)+'/../man/detroit-yard.5'
end

Public Instance Methods

assemble(station, options={}) click to toggle source
# File lib/detroit-yard.rb, line 112
def assemble(station, options={})
  case station
  when :document then document
  when :reset    then reset
  when :clean    then clean
  when :purge    then purge
  end
end
assemble?(station, options={}) click to toggle source
# File lib/detroit-yard.rb, line 102
def assemble?(station, options={})
  case station
  when :document then true
  when :reset    then true
  when :clean    then true
  when :purge    then true
  end
end
clean() click to toggle source

TODO: remove .yardoc ?

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

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

# File lib/detroit-yard.rb, line 126
def current?
  if outofdate?(output, *(resolved_files + resolved_topfiles))
    false
  else
    "YARD docs are current (#{output})."
  end
end
document() click to toggle source

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

# File lib/detroit-yard.rb, line 138
def document
  title    = self.title
  output   = self.output
  readme   = self.readme
  template = self.template
  #exclude  = self.exclude
  extra    = self.extra

  # TODO: add to resolved_topfiles ?
  readme = Dir.glob(readme, File::FNM_CASEFOLD).first

  if (msg = current?) && ! force?
    report msg
  else
    if !yardopts
      status "Generating YARD documentation in #{output}."
    end

    #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)

    if yardopts
      argv = []
    else
      argv = []
      argv.concat(String === extra ? extra.split(/\s+/) : extra)
      argv.concat ['--output-dir', output] if output
      argv.concat ['--readme', readme] if readme
      argv.concat ['--template', template] if template
      argv.concat ['--title', title] if title
      #argv.concat ['--exclude', exclude]
      argv.concat resolved_files
      argv.concat ['-', *resolved_topfiles]
    end

    yard_target(output, argv)

    touch(output) if File.directory?(output) unless yardopts
  end
end
files=(list) click to toggle source
# File lib/detroit-yard.rb, line 69
def files=(list)
  @resolved_files = nil
  @files = list.to_list
end
purge() click to toggle source

Remove yardoc output directory.

# File lib/detroit-yard.rb, line 194
def purge
  if directory?(output)
    rm_r(output)
    status "Removed #{output}" unless trial?
  end
end
reset() click to toggle source

Mark the output directory as out of date.

# File lib/detroit-yard.rb, line 182
def reset
  if directory?(output) && !yardopts
    utime(0, 0, output)
    report "Reset #{output}" #unless trial?
  end
end
topfiles=(list) click to toggle source

Set topfiles list.

# File lib/detroit-yard.rb, line 81
def topfiles=(list)
  @resolved_topfiles = nil
  @topfiles = list.to_list
end

Private Instance Methods

initialize_defaults() click to toggle source
# File lib/detroit-yard.rb, line 204
def initialize_defaults
  @title    = metadata.title
  @files    = metadata.loadpath + ['bin'] # DEFAULT_FILES
  @topfiles = ['[A-Z]*']

  @output   = Dir[DEFAULT_OUTPUT_MATCH].first || DEFAULT_OUTPUT
  @readme   = DEFAULT_README
  @extra    = DEFAULT_EXTRA
  @template = ENV['YARD_TEMPLATE'] || DEFAULT_TEMPLATE
end
initialize_options(options) click to toggle source

If there are no options set than default to using the .yardopts file (if it exists).

Calls superclass method
# File lib/detroit-yard.rb, line 219
def initialize_options(options)
  if !options.keys.any?{ |k| LOCAL_SETTINGS.include?(k) }
    @yardopts = true if (project.root + '.yardopts').exist?
  end
  super(options)
end
initialize_requires() click to toggle source

Require yard library.

# File lib/detroit-yard.rb, line 260
def initialize_requires
  require 'yard'
end
resolved_files() click to toggle source
# File lib/detroit-yard.rb, line 227
def resolved_files
  @resolved_files ||= (
    amass(files, exclude || [], ignore || []).uniq
  )
end
resolved_topfiles() click to toggle source
# File lib/detroit-yard.rb, line 234
def resolved_topfiles
  @resolved_topfiles ||= (
    amass(topfiles, exclude || [], ignore || [])
  )
end
yard_target(output, argv=[]) click to toggle source

Generate yardocs for input targets.

# File lib/detroit-yard.rb, line 241
def yard_target(output, argv=[])
  # remove old yardocs
  #rm_r(output) if exist?(output) and safe?(output)
  #options['output-dir'] = output
  #args = "#{extra} " + [input, options].to_console
  #argv = args.split(/\s+/)

  args = argv.join(' ')
  cmd  = "yardoc " + args

  trace(cmd)

  if trial?
  else
    YARD::CLI::Yardoc.run(*argv)
  end
end