Class: Gemma::RakeTasks::YardTasks

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

Overview

Create tasks to generate documentation with yard (yardoc) if it is available.

The gemspec’s require_paths and extra_rdoc_files are documented by default.

Unfortunately, yardoc’s command line options are largely incompatible with those for rdoc, but the --main and --title options from rdoc_options are passed through to yardoc by default. The short forms -m and -t of these arguments are also passed on as --main and --title to yardoc (note that -m and -t mean different things to yardoc than to rdoc!). Note that any files (that is, non-options) in rdoc_options are also ignored.

If you want to further customize your yardoc output, you can add options in the with_gemspec_file configuration block or use a .yardopts file.

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

Instance Attribute Summary collapse

Attributes inherited from Plugin

#gemspec

Instance Method Summary collapse

Constructor Details

#initialize(gemspec) ⇒ YardTasks

Returns a new instance of YardTasks.

Parameters:

  • gemspec (Gem::Specification) 


34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 34

def initialize(gemspec)
  super(gemspec)

  # Defaults.
  @task_name = :yard
  @output = 'yard'
  @with_yardoc_task = nil

  # Extract supported rdoc options and add to the default yard options.
  # Keep track of main, if it is given, because we have to remove it from
  # the extra files list (otherwise it shows up twice in the output).
  @main = Options.extract(%w(-m --main), gemspec.rdoc_options).argument
  @title = Options.extract(%w(-t --title), gemspec.rdoc_options).argument

  @options = []

  # Yard splits up the files from the 'extra' files.
  @files = gemspec.require_paths.dup
  @extra_files = gemspec.extra_rdoc_files.dup
  @extra_files.delete(main) if main
end

Instance Attribute Details

#extra_files ⇒ Array<String>

Extra files (e.g. FAQ, LICENSE) to be processed by yard; these are extracted from the gemspec.

Returns:

  • (Array<String>) 


100
101
102
 
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 100

def extra_files
  @extra_files
end

#files ⇒ Array<String>

Ruby files to be processed by yard; these are extracted from the gemspec; by default these are the require_paths.

Returns:

  • (Array<String>) 


92
93
94
 
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 92

def files
  @files
end

#main ⇒ String?

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

Returns:

  • (String, nil) 


76
77
78
 
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 76

def main
  @main
end

#options ⇒ Array<String>

Options to be passed to yard; note that the #output option and the #files and #extra_files lists are handled separately.

Returns:

  • (Array<String>) 


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

def options
  @options
end

#output ⇒ String

Name of output directory (the yard option –output); defaults to yard.

Returns:

  • (String) 


68
69
70
 
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 68

def output
  @output
end

#task_name ⇒ Symbol

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

Returns:

  • (Symbol) 


61
62
63
 
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 61

def task_name
  @task_name
end

#title ⇒ String?

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

Returns:

  • (String, nil) 


84
85
86
 
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 84

def title
  @title
end

Instance Method Details

#create_rake_tasks ⇒ nil

Internal method; see Plugin#create_rake_tasks.

Returns:

  • (nil) 


133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 133

def create_rake_tasks
  YARD::Rake::YardocTask.new do |yd|
    yd.name    = task_name
    yd.options = complete_options
    yd.files   = files
    yd.files.push('-', *extra_files) unless extra_files.empty?
    @with_yardoc_task.call(yd) if @with_yardoc_task
  end
  CLOBBER.include(output)
  CLOBBER.include('.yardoc')
  nil
rescue LoadError
  nil # Assume yard is not installed.
end

#with_yardoc_task {|yd| ... } ⇒ nil

Customize the yardoc task (e.g. to add blocks to run before or after the docs are generated).

is generated

Yields:

  • (yd) —

    called after the defaults are set but before the yard task

Yield Parameters:

  • yd (YARD::Rake::YardocTask)

Returns:

  • (nil) 


121
122
123
124
 
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 121

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