Class: Gemma::RakeTasks::RDocTasks

Inherits:
Plugin
  • Object
show all
Defined in:
lib/gemma/rake_tasks/rdoc_tasks.rb

Overview

Create tasks for generating rdoc API documentation with settings from the gemspec.

The default settings are based on the require_paths, rdoc_options and extra_rdoc_files data in the gemspec.

This plugin is based on the Rake::RDocTask that comes bundled with rdoc. If you need an option that isn’t exposed by the plugin, you can modify the RDocTask object directly in a block passed to #with_rdoc_task.

Instance Attribute Summary collapse

Attributes inherited from Plugin

#gemspec

Instance Method Summary collapse

Constructor Details

#initialize(gemspec) ⇒ RDocTasks

Returns a new instance of RDocTasks.

Parameters:

  • gemspec (Gem::Specification) 


21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/gemma/rake_tasks/rdoc_tasks.rb', line 21

def initialize gemspec
  super(gemspec)

  # Defaults.
  @task_name = :rdoc
  @with_rdoc_task = nil

  # I'm not sure whether it's a good idea to pass -o in the gemspec, but
  # for now we'll handle it, because it's needed in the Rakefile.
  @options = gemspec.rdoc_options
  @output, @options = Options.extract(%w(-o --output --op), @options).to_a
  @output ||= 'rdoc'

  # Extract --main, --title and --template so RDocTask can have them.
  @main, @options  = Options.extract(%w(-m --main), @options).to_a
  @title, @options = Options.extract(%w(-t --title), @options).to_a
  @template, @options = Options.extract(%w(-T --template), @options).to_a

  @files = gemspec.require_paths + gemspec.extra_rdoc_files
end

Instance Attribute Details

#files ⇒ Array<String>

Files and directories to be processed by rdoc; extracted from gemspec; by default, these are the gem’s require_paths and extra_rdoc_files.

Returns:

  • (Array<String>) 


87
88
89
 
# File 'lib/gemma/rake_tasks/rdoc_tasks.rb', line 87

def files
  @files
end

#main ⇒ String?

Name of file to display in index.html (the rdoc option –main); extracted from gemspec; defaults to nil (none).

Returns:

  • (String, nil) 


63
64
65
 
# File 'lib/gemma/rake_tasks/rdoc_tasks.rb', line 63

def main
  @main
end

#options ⇒ Array<String>

Options to be passed to rdoc; extracted from gemspec; note that the #output, #main, #title and #template options and the #files list are handled separately.

Returns:

  • (Array<String>) 


96
97
98
 
# File 'lib/gemma/rake_tasks/rdoc_tasks.rb', line 96

def options
  @options
end

#output ⇒ String

Name of output directory (the rdoc option –output); extracted from gemspec; defaults to rdoc.

Returns:

  • (String) 


55
56
57
 
# File 'lib/gemma/rake_tasks/rdoc_tasks.rb', line 55

def output
  @output
end

#task_name ⇒ Symbol

Name of rake task used to generate these docs; defaults to rdoc.

Returns:

  • (Symbol) 


47
48
49
 
# File 'lib/gemma/rake_tasks/rdoc_tasks.rb', line 47

def task_name
  @task_name
end

#template ⇒ String?

Name of template used to generate html output (the rdoc option –template); extracted from gemspec; defaults to nil (unspecified).

Returns:

  • (String, nil) 


79
80
81
 
# File 'lib/gemma/rake_tasks/rdoc_tasks.rb', line 79

def template
  @template
end

#title ⇒ String?

Title for HTML output (the rdoc option –title); extracted from gemspec; defaults to nil (unspecified).

Returns:

  • (String, nil) 


71
72
73
 
# File 'lib/gemma/rake_tasks/rdoc_tasks.rb', line 71

def title
  @title
end

Instance Method Details

#create_rake_tasks ⇒ nil

Internal method; see Plugin#create_rake_tasks.

Returns:

  • (nil) 


120
121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/gemma/rake_tasks/rdoc_tasks.rb', line 120

def create_rake_tasks
  Rake::RDocTask.new(self.task_name) do |rd|
    rd.rdoc_dir      = self.output
    rd.rdoc_files    = self.files
    rd.title         = self.title
    rd.main          = self.main
    rd.template      = self.template
    rd.options       = self.options
    @with_rdoc_task.call(rd) if @with_rdoc_task
  end
  CLOBBER.include(self.output)

  nil
end

#with_rdoc_task {|rd| ... } ⇒ nil

Customize the rdoc task.

are generated

Yields:

  • (rd) —

    called after the defaults are set but before the rdoc tasks

Yield Parameters:

  • rd (Rake::RDocTask)

Returns:

  • (nil) 


108
109
110
111
 
# File 'lib/gemma/rake_tasks/rdoc_tasks.rb', line 108

def with_rdoc_task &block
  @with_rdoc_task = block
  nil
end