Class: Gemma::RakeTasks::YardTasks
- 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
-
#extra_files ⇒ Array<String>
Extra files (e.g. FAQ, LICENSE) to be processed by yard; these are extracted from the gemspec.
-
#files ⇒ Array<String>
Ruby files to be processed by yard; these are extracted from the gemspec; by default these are the
require_paths
. -
#main ⇒ String?
Name of file to display in index.html (the yard option –main); extracted from gemspec; defaults to nil (none).
-
#options ⇒ Array<String>
Options to be passed to yard; note that the #output option and the #files and #extra_files lists are handled separately.
-
#output ⇒ String
Name of output directory (the yard option –output); defaults to yard.
-
#task_name ⇒ Symbol
Name of rake task used to generate these docs; defaults to yard.
-
#title ⇒ String?
Title for HTML output (the yard option –title); extracted from gemspec; defaults to nil (unspecified).
Attributes inherited from Plugin
Instance Method Summary collapse
-
#create_rake_tasks ⇒ nil
Internal method; see Plugin#create_rake_tasks.
-
#initialize(gemspec) ⇒ YardTasks
constructor
A new instance of YardTasks.
-
#with_yardoc_task {|yd| ... } ⇒ nil
Customize the yardoc task (e.g. to add blocks to run before or after the docs are generated).
Constructor Details
#initialize(gemspec) ⇒ YardTasks
Returns a new instance of YardTasks.
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 33 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.).argument @title = Options.extract(%w(-t --title), gemspec.).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.
99 100 101 |
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 99 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
.
91 92 93 |
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 91 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).
75 76 77 |
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 75 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.
107 108 109 |
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 107 def @options end |
#output ⇒ String
Name of output directory (the yard option –output); defaults to yard.
67 68 69 |
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 67 def output @output end |
#task_name ⇒ Symbol
Name of rake task used to generate these docs; defaults to yard.
60 61 62 |
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 60 def task_name @task_name end |
#title ⇒ String?
Title for HTML output (the yard option –title); extracted from gemspec; defaults to nil (unspecified).
83 84 85 |
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 83 def title @title end |
Instance Method Details
#create_rake_tasks ⇒ nil
Internal method; see Plugin#create_rake_tasks.
132 133 134 135 136 137 138 139 140 141 142 143 144 145 |
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 132 def create_rake_tasks YARD::Rake::YardocTask.new do |yd| yd.name = self.task_name yd. = yd.files = self.files yd.files.push('-', *self.extra_files) unless self.extra_files.empty? @with_yardoc_task.call(yd) if @with_yardoc_task end CLOBBER.include(self.output) CLOBBER.include('.yardoc') nil rescue LoadError # 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
120 121 122 123 |
# File 'lib/gemma/rake_tasks/yard_tasks.rb', line 120 def with_yardoc_task &block @with_yardoc_task = block nil end |