Class: Toys::Templates::Yardoc

Inherits:
Object
  • Object
show all
Includes:
Toys::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

Methods included from Toys::Template

create

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, context_directory: nil) ⇒ 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.

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

    A custom context directory to use when executing this tool.



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
123
124
125
126
 
# File 'lib/toys/templates/yardoc.rb', line 84

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,
               context_directory: nil)
  @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
  @context_directory = context_directory
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) 


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

def bundler=(value)
  @bundler = value
end

#context_directory=(value) ⇒ String

Custom context directory for this tool.

Parameters:

  • value (String)

Returns:

  • (String) 


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

def context_directory=(value)
  @context_directory = 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) 


198
199
200
 
# File 'lib/toys/templates/yardoc.rb', line 198

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) 


189
190
191
 
# File 'lib/toys/templates/yardoc.rb', line 189

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


153
154
155
 
# File 'lib/toys/templates/yardoc.rb', line 153

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) 


275
276
277
 
# File 'lib/toys/templates/yardoc.rb', line 275

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) 


145
146
147
 
# File 'lib/toys/templates/yardoc.rb', line 145

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) 


162
163
164
 
# File 'lib/toys/templates/yardoc.rb', line 162

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) 


171
172
173
 
# File 'lib/toys/templates/yardoc.rb', line 171

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) 


230
231
232
 
# File 'lib/toys/templates/yardoc.rb', line 230

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) 


248
249
250
 
# File 'lib/toys/templates/yardoc.rb', line 248

def markup=(value)
  @markup = value
end

#name=(value) ⇒ String

Name of the tool to create.

Parameters:

  • value (String)

Returns:

  • (String) 


134
135
136
 
# File 'lib/toys/templates/yardoc.rb', line 134

def name=(value)
  @name = value
end

#options=(value) ⇒ Array<String>

Additional options to pass to YARD

Parameters:

  • value (Array<String>)

Returns:

  • (Array<String>) 


283
284
285
 
# File 'lib/toys/templates/yardoc.rb', line 283

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) 


180
181
182
 
# File 'lib/toys/templates/yardoc.rb', line 180

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) 


239
240
241
 
# File 'lib/toys/templates/yardoc.rb', line 239

def readme=(value)
  @readme = value
end

#show_private=(value) ⇒ Boolean

Whether to document private methods.

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


222
223
224
 
# File 'lib/toys/templates/yardoc.rb', line 222

def show_private=(value)
  @show_private = value
end

#show_protected=(value) ⇒ Boolean

Whether to document protected methods.

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


214
215
216
 
# File 'lib/toys/templates/yardoc.rb', line 214

def show_protected=(value)
  @show_protected = value
end

#show_public=(value) ⇒ Boolean

Whether to document public methods.

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


206
207
208
 
# File 'lib/toys/templates/yardoc.rb', line 206

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


291
292
293
 
# File 'lib/toys/templates/yardoc.rb', line 291

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) 


257
258
259
 
# File 'lib/toys/templates/yardoc.rb', line 257

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) 


266
267
268
 
# File 'lib/toys/templates/yardoc.rb', line 266

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) 


324
325
326
327
 
# File 'lib/toys/templates/yardoc.rb', line 324

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