Class: Buildr::Doc::DocTask

Inherits:
Rake::Task show all
Defined in:
lib/buildr/core/doc.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods inherited from Rake::Task

#invoke, #invoke_with_call_chain

Constructor Details

#initialize(*args) ⇒ DocTask

:nodoc:



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/buildr/core/doc.rb', line 79

def initialize(*args) #:nodoc:
  super
  @options = {}
  @classpath = []
  @sourcepath = []
  @files = FileList[]
  enhance do |task|
    rm_rf target.to_s
    mkdir_p target.to_s

    engine.generate(source_files, File.expand_path(target.to_s),
      options.merge(:classpath => classpath, :sourcepath => sourcepath))

    touch target.to_s
  end
end

Instance Attribute Details

#classpath ⇒ Object

Classpath dependencies.



69
70
71
 
# File 'lib/buildr/core/doc.rb', line 69

def classpath
  @classpath
end

#options ⇒ Object (readonly)

Returns the documentation tool options.



75
76
77
 
# File 'lib/buildr/core/doc.rb', line 75

def options
  @options
end

#project ⇒ Object (readonly)

:nodoc:



77
78
79
 
# File 'lib/buildr/core/doc.rb', line 77

def project
  @project
end

#sourcepath ⇒ Object

Additional sourcepaths that are not part of the documented files.



72
73
74
 
# File 'lib/buildr/core/doc.rb', line 72

def sourcepath
  @sourcepath
end

#target ⇒ Object (readonly)

The target directory for the generated documentation files.



66
67
68
 
# File 'lib/buildr/core/doc.rb', line 66

def target
  @target
end

Instance Method Details

#engine ⇒ Object 



162
163
164
 
# File 'lib/buildr/core/doc.rb', line 162

def engine
  @engine ||= guess_engine
end

#engine?(clazz) ⇒ Boolean

:call-seq:

engine?(clazz) => boolean

Check if the underlying engine is an instance of the given class

Returns:

  • (Boolean) 


170
171
172
173
174
175
176
177
 
# File 'lib/buildr/core/doc.rb', line 170

def engine?(clazz)
  begin
    @engine ||= guess_engine if project.compile.language
  rescue
    return false
  end
  @engine.is_a?(clazz) if @engine
end

#exclude(*files) ⇒ Object

:call-seq:

exclude(*files) => self

Excludes source files and directories from generating the documentation.



129
130
131
132
 
# File 'lib/buildr/core/doc.rb', line 129

def exclude(*files)
  @files.exclude *files.collect{|f|File.expand_path(f)}
  self
end

#from(*sources) ⇒ Object

:call-seq:

from(*sources) => self

Includes files, directories and projects in the documentation and returns self.

You can call this method with source files and directories containing source files to include these files in the documentation, similar to #include. You can also call this method with projects. When called with a project, it includes all the source files compiled by that project and classpath dependencies used when compiling.

For example:

doc.from projects('myapp:foo', 'myapp:bar')



191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/buildr/core/doc.rb', line 191

def from(*sources)
  sources.flatten.each do |source|
    case source
    when Project
      self.enhance source.prerequisites
      self.include source.compile.sources
      self.with source.compile.dependencies
    when Rake::Task, String
      self.include source
    else
      fail "Don't know how to generate documentation from #{source || 'nil'}"
    end
  end
  self
end

#include(*files) ⇒ Object

:call-seq:

include(*files) => self

Includes additional source files and directories when generating the documentation and returns self. When specifying a directory, includes all source files in that directory.



114
115
116
117
118
119
120
121
122
123
 
# File 'lib/buildr/core/doc.rb', line 114

def include(*files)
  files.each do |file|
    if file.respond_to? :to_ary
      include(*file.to_ary)
    else
      @files.include *files.flatten.compact.collect { |f| File.expand_path(f.to_s) }
    end
  end
  self
end

#into(path) ⇒ Object

:call-seq:

into(path) => self

Sets the target directory and returns self. This will also set the Javadoc task as a prerequisite to a file task on the target directory.

For example:

package :zip, :classifier=>'docs', :include=>doc.target



104
105
106
107
 
# File 'lib/buildr/core/doc.rb', line 104

def into(path)
  @target = file(path.to_s).enhance([self]) unless @target && @target.to_s == path.to_s
  self
end

#needed? ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


219
220
221
222
223
 
# File 'lib/buildr/core/doc.rb', line 219

def needed? #:nodoc:
  return false if source_files.empty?
  return true unless File.exist?(target.to_s)
  source_files.map { |src| File.stat(src.to_s).mtime }.max > File.stat(target.to_s).mtime
end

#prerequisites ⇒ Object

:nodoc:



207
208
209
 
# File 'lib/buildr/core/doc.rb', line 207

def prerequisites #:nodoc:
  super + @files + classpath + sourcepath
end

#source_files ⇒ Object

:nodoc:



211
212
213
214
215
216
217
 
# File 'lib/buildr/core/doc.rb', line 211

def source_files #:nodoc:
  @source_files ||= @files.map(&:to_s).map do |file|
    Array(engine.class.source_ext).map do |ext|
      File.directory?(file) ? FileList[File.join(file, "**/*.#{ext}")] : File.expand_path(file)
    end
  end.flatten.reject { |file| @files.exclude?(file) }
end

#using(*args) ⇒ Object

:call-seq:

using(options) => self

Sets the documentation tool options from a hash and returns self.

For example:

doc.using :windowtitle=>'My application'
doc.using :vscaladoc



151
152
153
154
155
156
157
158
159
160
 
# File 'lib/buildr/core/doc.rb', line 151

def using(*args)
  args.pop.each { |key, value| @options[key.to_sym] = value } if Hash === args.last

  until args.empty?
    new_engine = Doc.select_by_name(args.pop)
    @engine = new_engine.new(project) unless new_engine.nil?
  end

  self
end

#with(*specs) ⇒ Object

:call-seq:

with(*artifacts) => self

Adds files and artifacts as classpath dependencies, and returns self.



138
139
140
141
 
# File 'lib/buildr/core/doc.rb', line 138

def with(*specs)
  @classpath |= Buildr.artifacts(specs.flatten).uniq
  self
end