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) 


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

def initialize(gemspec)
  super

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


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

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) 


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

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


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

def options
  @options
end

#output ⇒ String

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

Returns:

  • (String) 


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

def output
  @output
end

#task_name ⇒ Symbol

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

Returns:

  • (Symbol) 


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

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) 


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

def template
  @template
end

#title ⇒ String?

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

Returns:

  • (String, nil) 


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

def title
  @title
end

Instance Method Details

#create_rake_tasks ⇒ nil

Internal method; see Plugin#create_rake_tasks.

Returns:

  • (nil) 


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

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


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

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