Class: Toys::Templates::Yardoc

Inherits:
Object
  • Object
show all
Includes:
Template
Defined in:
lib/toys/templates/yardoc.rb

Overview

A template that generates yardoc tools.

Constant Summary collapse

DEFAULT_GEM_VERSION_REQUIREMENTS =

Default version requirements for the yard gem.

Returns:

  • (String) 
["~> 0.9"].freeze
DEFAULT_TOOL_NAME =

Default tool name

Returns:

  • (String) 
"yardoc"
DEFAULT_FILES =

Default file globs

Returns:

  • (Array<String>) 
["lib/**/*.rb"].freeze
DEFAULT_OUTPUT_DIR =

Default output directory

Returns:

  • (String) 
"doc"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name: nil, gem_version: nil, files: nil, generate_output: true, generate_output_flag: false, output_dir: nil, fail_on_warning: false, fail_on_undocumented_objects: false, show_public: true, show_protected: false, show_private: false, hide_private_tag: false, readme: nil, markup: nil, template: nil, template_path: nil, format: nil, options: [], stats_options: [], bundler: false) ⇒ Yardoc

Create the template settings for the Yardoc template.

Parameters:

  • name (String) (defaults to: nil) —

    Name of the tool to create. Defaults to DEFAULT_TOOL_NAME.

  • gem_version (String, Array<String>) (defaults to: nil) —

    Version requirements for the yard gem. Defaults to DEFAULT_GEM_VERSION_REQUIREMENTS.

  • files (Array<String>) (defaults to: nil) —

    An array of globs indicating the files to document. Defaults to DEFAULT_FILES.

  • generate_output (Boolean) (defaults to: true) —

    Whether to generate output. Setting to false causes yardoc to emit warnings/errors but not generate html. Defaults to true.

  • generate_output_flag (Boolean) (defaults to: false) —

    Whether to create a flag --[no-]output that can control whether output is generated. Defaults to false.

  • output_dir (String, nil) (defaults to: nil) —

    Output directory. Defaults to DEFAULT_OUTPUT_DIR.

  • fail_on_warning (Boolean) (defaults to: false) —

    Whether the tool should return a nonzero error code if any warnings happen. Defaults to false.

  • fail_on_undocumented_objects (Boolean) (defaults to: false) —

    Whether the tool should return a nonzero error code if any objects remain undocumented. Defaults to false.

  • show_public (Boolean) (defaults to: true) —

    Show public methods. Defaults to true.

  • show_protected (Boolean) (defaults to: false) —

    Show protected methods. Defaults to false.

  • show_private (Boolean) (defaults to: false) —

    Show private methods. Defaults to false.

  • hide_private_tag (Boolean) (defaults to: false) —

    Hide methods with the @private tag. Defaults to false.

  • readme (String, nil) (defaults to: nil) —

    Name of the readme file used as the title page. If not provided, YARD will choose a default.

  • markup (String, nil) (defaults to: nil) —

    Markup style used in documentation. If not provided, YARD will choose a default, likely "rdoc".

  • template (String, nil) (defaults to: nil) —

    Template to use. If not provided, YARD will choose a default.

  • template_path (String, nil) (defaults to: nil) —

    The optional template path to look for templates in.

  • format (String, nil) (defaults to: nil) —

    The output format for the template. If not provided, YARD will choose a default, likely "html".

  • options (Array<String>) (defaults to: []) —

    Additional options passed to YARD

  • stats_options (Array<String>) (defaults to: []) —

    Additional stats options passed to YARD

  • bundler (Boolean, Hash) (defaults to: false) —

    If false (the default), bundler is not enabled for this tool. If true or a Hash of options, bundler is enabled. See the documentation for the bundler mixin for information on available options.



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/toys/templates/yardoc.rb', line 82

def initialize(name: nil,
               gem_version: nil,
               files: nil,
               generate_output: true,
               generate_output_flag: false,
               output_dir: nil,
               fail_on_warning: false,
               fail_on_undocumented_objects: false,
               show_public: true,
               show_protected: false,
               show_private: false,
               hide_private_tag: false,
               readme: nil,
               markup: nil,
               template: nil,
               template_path: nil,
               format: nil,
               options: [],
               stats_options: [],
               bundler: false)
  @name = name
  @gem_version = gem_version
  @files = files
  @generate_output = generate_output
  @generate_output_flag = generate_output_flag
  @output_dir = output_dir
  @fail_on_warning = fail_on_warning
  @fail_on_undocumented_objects = fail_on_undocumented_objects
  @show_public = show_public
  @show_protected = show_protected
  @show_private = show_private
  @hide_private_tag = hide_private_tag
  @readme = readme
  @markup = markup
  @template = template
  @template_path = template_path
  @format = format
  @options = options
  @stats_options = stats_options
  @bundler = bundler
end

Instance Attribute Details

#bundler=(value) ⇒ Boolean, Hash (writeonly)

Set the bundler state and options for this tool.

Pass false to disable bundler. Pass true or a hash of options to enable bundler. See the documentation for the bundler mixin for information on the options that can be passed.

Parameters:

  • value (Boolean, Hash)

Returns:

  • (Boolean, Hash) 


300
301
302
 
# File 'lib/toys/templates/yardoc.rb', line 300

def bundler=(value)
  @bundler = value
end

#fail_on_undocumented_objects=(value) ⇒ Boolean

Whether the tool should return a nonzero error code if any objects remain undocumented.

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


194
195
196
 
# File 'lib/toys/templates/yardoc.rb', line 194

def fail_on_undocumented_objects=(value)
  @fail_on_undocumented_objects = value
end

#fail_on_warning=(value) ⇒ Boolean

Whether the tool should return a nonzero error code if any warnings happen.

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


185
186
187
 
# File 'lib/toys/templates/yardoc.rb', line 185

def fail_on_warning=(value)
  @fail_on_warning = value
end

#files=(value) ⇒ Array<String>

An array of globs indicating which files to document.

Parameters:

  • value (Array<String>)

Returns:

  • (Array<String>) 


149
150
151
 
# File 'lib/toys/templates/yardoc.rb', line 149

def files=(value)
  @files = value
end

#format=(value) ⇒ String?

Output format for the template. If set to nil, YARD will choose a default, likely "html".

Parameters:

  • value (String, nil)

Returns:

  • (String, nil) 


271
272
273
 
# File 'lib/toys/templates/yardoc.rb', line 271

def format=(value)
  @format = value
end

#gem_version=(value) ⇒ String, ...

Version requirements for the rdoc gem. If set to nil, uses the bundled version if bundler is enabled, or defaults to DEFAULT_GEM_VERSION_REQUIREMENTS if bundler is not enabled.

Parameters:

  • value (String, Array<String>, nil)

Returns:

  • (String, Array<String>, nil) 


141
142
143
 
# File 'lib/toys/templates/yardoc.rb', line 141

def gem_version=(value)
  @gem_version = value
end

#generate_output=(value) ⇒ Boolean

Whether to generate output. Setting to false causes yardoc to emit warnings/errors but not generate html.

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


158
159
160
 
# File 'lib/toys/templates/yardoc.rb', line 158

def generate_output=(value)
  @generate_output = value
end

#generate_output_flag=(value) ⇒ Boolean

Whether to create a flag --[no-]output that can control whether output is generated.

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


167
168
169
 
# File 'lib/toys/templates/yardoc.rb', line 167

def generate_output_flag=(value)
  @generate_output_flag = value
end

#hide_private_tag=(value) ⇒ Boolean

Whether to hide methods with the @private tag.

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


226
227
228
 
# File 'lib/toys/templates/yardoc.rb', line 226

def hide_private_tag=(value)
  @hide_private_tag = value
end

#markup=(value) ⇒ String?

Markup style used in documentation. If set to nil, YARD will choose a default, likely "rdoc".

Parameters:

  • value (String, nil)

Returns:

  • (String, nil) 


244
245
246
 
# File 'lib/toys/templates/yardoc.rb', line 244

def markup=(value)
  @markup = value
end

#name=(value) ⇒ String

Name of the tool to create.

Parameters:

  • value (String)

Returns:

  • (String) 


130
131
132
 
# File 'lib/toys/templates/yardoc.rb', line 130

def name=(value)
  @name = value
end

#options=(value) ⇒ Array<String>

Additional options to pass to YARD

Parameters:

  • value (Array<String>)

Returns:

  • (Array<String>) 


279
280
281
 
# File 'lib/toys/templates/yardoc.rb', line 279

def options=(value)
  @options = value
end

#output_dir=(value) ⇒ String?

Name of directory to receive html output files. If set to nil, defaults to DEFAULT_OUTPUT_DIR.

Parameters:

  • value (String, nil)

Returns:

  • (String, nil) 


176
177
178
 
# File 'lib/toys/templates/yardoc.rb', line 176

def output_dir=(value)
  @output_dir = value
end

#readme=(value) ⇒ String?

Name of the readme file used as the title page. If set to nil, YARD will choose a default.

Parameters:

  • value (String, nil)

Returns:

  • (String, nil) 


235
236
237
 
# File 'lib/toys/templates/yardoc.rb', line 235

def readme=(value)
  @readme = value
end

#show_private=(value) ⇒ Boolean

Whether to document private methods.

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


218
219
220
 
# File 'lib/toys/templates/yardoc.rb', line 218

def show_private=(value)
  @show_private = value
end

#show_protected=(value) ⇒ Boolean

Whether to document protected methods.

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


210
211
212
 
# File 'lib/toys/templates/yardoc.rb', line 210

def show_protected=(value)
  @show_protected = value
end

#show_public=(value) ⇒ Boolean

Whether to document public methods.

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


202
203
204
 
# File 'lib/toys/templates/yardoc.rb', line 202

def show_public=(value)
  @show_public = value
end

#stats_options=(value) ⇒ Array<String>

Additional stats options to pass to YARD

Parameters:

  • value (Array<String>)

Returns:

  • (Array<String>) 


287
288
289
 
# File 'lib/toys/templates/yardoc.rb', line 287

def stats_options=(value)
  @stats_options = value
end

#template=(value) ⇒ String?

Template to use. If set to nil, YARD will choose a default.

Parameters:

  • value (String, nil)

Returns:

  • (String, nil) 


253
254
255
 
# File 'lib/toys/templates/yardoc.rb', line 253

def template=(value)
  @template = value
end

#template_path=(value) ⇒ String?

Directory path to look for templates in. If set to nil, no additional template lookup paths will be used.

Parameters:

  • value (String, nil)

Returns:

  • (String, nil) 


262
263
264
 
# File 'lib/toys/templates/yardoc.rb', line 262

def template_path=(value)
  @template_path = value
end

Instance Method Details

#use_bundler(**opts) ⇒ self

Activate bundler for this tool.

See the documentation for the bundler mixin for information on the options that can be passed.

Parameters:

  • opts (keywords) —

    Options for bundler

Returns:

  • (self) 


312
313
314
315
 
# File 'lib/toys/templates/yardoc.rb', line 312

def use_bundler(**opts)
  @bundler = opts
  self
end