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) 


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

def initialize(gemspec)
  super

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


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

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


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

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) 


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

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


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

def options
  @options
end

#output ⇒ String

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

Returns:

  • (String) 


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

def output
  @output
end

#task_name ⇒ Symbol

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

Returns:

  • (Symbol) 


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

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) 


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

def title
  @title
end

Instance Method Details

#create_rake_tasks ⇒ nil

Internal method; see Plugin#create_rake_tasks.

Returns:

  • (nil) 


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

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


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

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