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 



156
157
158
 
# File 'lib/buildr/core/doc.rb', line 156

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



164
165
166
167
168
169
170
171
 
# File 'lib/buildr/core/doc.rb', line 164

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.



123
124
125
126
 
# File 'lib/buildr/core/doc.rb', line 123

def exclude(*files)
  @files.exclude *files
  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')



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/buildr/core/doc.rb', line 185

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
 
# File 'lib/buildr/core/doc.rb', line 114

def include(*files)
  @files.include *files.flatten.compact
  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:



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

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:



201
202
203
 
# File 'lib/buildr/core/doc.rb', line 201

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

#source_files ⇒ Object

:nodoc:



205
206
207
208
209
210
211
 
# File 'lib/buildr/core/doc.rb', line 205

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



145
146
147
148
149
150
151
152
153
154
 
# File 'lib/buildr/core/doc.rb', line 145

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.



132
133
134
135
 
# File 'lib/buildr/core/doc.rb', line 132

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