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) 


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

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


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

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) 


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

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


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

def options
  @options
end

#output ⇒ String

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

Returns:

  • (String) 


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

def output
  @output
end

#task_name ⇒ Symbol

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

Returns:

  • (Symbol) 


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

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) 


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

def template
  @template
end

#title ⇒ String?

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

Returns:

  • (String, nil) 


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

def title
  @title
end

Instance Method Details

#create_rake_tasks ⇒ nil

Internal method; see Plugin#create_rake_tasks.

Returns:

  • (nil) 


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

def create_rake_tasks
  Rake::RDocTask.new(task_name) do |rd|
    rd.rdoc_dir      = output
    rd.rdoc_files    = files
    rd.title         = title
    rd.main          = main
    rd.template      = template
    rd.options       = options
    @with_rdoc_task.call(rd) if @with_rdoc_task
  end
  CLOBBER.include(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) 


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

def with_rdoc_task(&block)
  @with_rdoc_task = block
  nil
end