Class: Detroit::Yard

Inherits:
Tool
  • Object
show all
Defined in:
lib/detroit-yard.rb

Overview

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.

– TODO: Should this autodetect .yardopts and use them unless told to do otherwise?

TODO: Not sure the #current? code is exactly correct, might get false negatives. ++

Constant Summary collapse

DEFAULT_OUTPUT =

Default location to store yard documentation files.

"doc"
DEFAULT_OUTPUT_MATCH =

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

"{site/,website/,doc/}yard"
DEFAULT_README =

Default main file.

"README"
DEFAULT_TEMPLATE =

Default template to use.

"default"
DEFAULT_EXTRA =

Deafult extra options to add to yardoc call.

''

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#exclude ⇒ Object

Paths to specifically exclude.



90
91
92
 
# File 'lib/detroit-yard.rb', line 90

def exclude
  @exclude
end

#extra ⇒ Object

Additional options passed to the yardoc command.



96
97
98
 
# File 'lib/detroit-yard.rb', line 96

def extra
  @extra
end

#files ⇒ Object

Which library files to document.



66
67
68
 
# File 'lib/detroit-yard.rb', line 66

def files
  @files
end

#ignore ⇒ Object

File patterns to ignore.



93
94
95
 
# File 'lib/detroit-yard.rb', line 93

def ignore
  @ignore
end

#output ⇒ Object

Directory in which to save yard files.



57
58
59
 
# File 'lib/detroit-yard.rb', line 57

def output
  @output
end

#readme ⇒ Object

Main file. This can be file pattern. (READMEDetroit::Yard.,,.txt)



63
64
65
 
# File 'lib/detroit-yard.rb', line 63

def readme
  @readme
end

#template ⇒ Object

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



60
61
62
 
# File 'lib/detroit-yard.rb', line 60

def template
  @template
end

#title ⇒ Object

Title of documents. Defaults to general metadata title field.



54
55
56
 
# File 'lib/detroit-yard.rb', line 54

def title
  @title
end

#topfiles ⇒ Object

Which project top-files to document.



78
79
80
 
# File 'lib/detroit-yard.rb', line 78

def topfiles
  @topfiles
end

#yardopts ⇒ Object

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



51
52
53
 
# File 'lib/detroit-yard.rb', line 51

def yardopts
  @yardopts
end

Class Method Details

.man_page ⇒ Object 



266
267
268
 
# File 'lib/detroit-yard.rb', line 266

def self.man_page
  File.dirname(__FILE__)+'/../man/detroit-yard.5'
end

Instance Method Details

#assemble(station, options = {}) ⇒ Object 



112
113
114
115
116
117
118
119
 
# 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 = {}) ⇒ Boolean

Returns:

  • (Boolean) 


102
103
104
105
106
107
108
109
 
# 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 ⇒ Object

TODO: remove .yardoc ?



190
191
 
# File 'lib/detroit-yard.rb', line 190

def clean
end

#current? ⇒ Boolean

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

Returns:

  • (Boolean) 


126
127
128
129
130
131
132
 
# 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 ⇒ Object

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



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# 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

#purge ⇒ Object

Remove yardoc output directory.



194
195
196
197
198
199
 
# File 'lib/detroit-yard.rb', line 194

def purge
  if directory?(output)
    rm_r(output)
    status "Removed #{output}" unless trial?
  end
end

#reset ⇒ Object

Mark the output directory as out of date.



182
183
184
185
186
187
 
# File 'lib/detroit-yard.rb', line 182

def reset
  if directory?(output) && !yardopts
    utime(0, 0, output)
    report "Reset #{output}" #unless trial?
  end
end