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
Paths to specifically exclude.
Additional options passed to the yardoc command.
Which library files to document.
File patterns to ignore.
Directory in which to save yard files.
Main file. This can be file pattern. (README{,.txt})
Template to use (defaults to ENV or 'default')
Title of documents. Defaults to general metadata title field.
Which project top-files to document.
If set to true, use `.yardopts` file and ignore other settings.
Public Class Methods
# File lib/detroit-yard.rb, line 266 def self.man_page File.dirname(__FILE__)+'/../man/detroit-yard.5' end
Public Instance Methods
# 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
# 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
TODO: remove .yardoc ?
# File lib/detroit-yard.rb, line 190 def clean end
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
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
# File lib/detroit-yard.rb, line 69 def files=(list) @resolved_files = nil @files = list.to_list end
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
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
Set topfiles list.
# File lib/detroit-yard.rb, line 81 def topfiles=(list) @resolved_topfiles = nil @topfiles = list.to_list end
Private Instance Methods
# 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
If there are no options set than default to using the .yardopts file (if it exists).
# 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
Require yard library.
# File lib/detroit-yard.rb, line 260 def initialize_requires require 'yard' end
# File lib/detroit-yard.rb, line 227 def resolved_files @resolved_files ||= ( amass(files, exclude || [], ignore || []).uniq ) end
# File lib/detroit-yard.rb, line 234 def resolved_topfiles @resolved_topfiles ||= ( amass(topfiles, exclude || [], ignore || []) ) end
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