Class: YARD::CLI::Yardoc

Inherits:
Command show all
Defined in:
lib/yard/cli/yardoc.rb

Overview

Yardoc is the default YARD CLI command (+yard doc+ and historic yardoc executable) used to generate and output (mainly) HTML documentation given a set of source files.

Usage

Main usage for this command is:

$ yardoc [options] [source_files [- extra_files]]

See yardoc –help for details on valid options.

Options File (.yardopts)

If a .yardopts file is found in the source directory being processed, YARD will use the contents of the file as arguments to the command, treating newlines as spaces. You can use shell-style quotations to group space delimited arguments, just like on the command line.

A valid .yardopts file might look like:

--no-private
--title "My Title"
--exclude foo --exclude bar
lib/**/*.erb
lib/**/*.rb -
HACKING.rdoc LEGAL COPYRIGHT

Note that Yardoc also supports the legacy RDoc style .document file, though this file can only specify source globs to parse, not options.

Queries (--query)

Yardoc supports queries to select specific code objects for which to generate documentation. For example, you might want to generate documentation only for your public API. If you’ve documented your public methods with @api public, you can use the following query to select all of these objects:

--query '@api.text == "public"'

Note that the syntax for queries is mostly Ruby with a few syntactic simplifications for meta-data tags. See the Verifier class for an overview of this syntax.

Adding Custom Ad-Hoc Meta-data Tags (--tag)

YARD allows specification of meta-data tags programmatically via the Tags::Library class, but often this is not practical for users writing documentation. To make adding custom tags easier, Yardoc has a few command-line switches for creating basic tags and displaying them in generated HTML output.

To specify a custom tag to be displayed in output, use any of the following:

  • --tag TAG:TITLE

  • --name-tag TAG:TITLE

  • --type-tag TAG:TITLE

  • --type-name-tag TAG:TITLE

  • --title-tag TAG:TITLE

“TAG:TITLE” is of the form: name:“Display Title”, for example:

--tag overload:"Overloaded Method"

See yardoc –help for a description of the various options.

Tags added in this way are automatically displayed in output. To add a meta-data tag that does not show up in output, use –hide-tag TAG. Note that you can also use this option on existing tags to hide builtin tags, for instance.

Processed Data Storage (.yardoc directory)

When Yardoc parses a source directory, it creates a .yardoc directory (by default, override with -b) at the root of the project. This directory contains marshal dumps for all raw object data in the source, so that you can access it later for various commands (stats, graph, etc.). This directory is also used as a cache for any future calls to yardoc so as to process only the files which have changed since the last call.

When Yardoc uses the cache in subsequent calls to yardoc, methods or classes that have been deleted from source since the last parsing will not be erased from the cache (YARD never deletes objects). In such a case, you should wipe the cache and do a clean parsing of the source tree. You can do this by deleting the .yardoc directory manually, or running Yardoc without --use-cache (-c).

See Also:

Since:

  • 0.2.1

Direct Known Subclasses

I18n, Stats

Constant Summary collapse

DEFAULT_YARDOPTS_FILE =

The configuration filename to load extra options from

Since:

  • 0.2.1

".yardopts"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Yardoc

Creates a new instance of the commandline utility

Since:

  • 0.2.1



208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
 
# File 'lib/yard/cli/yardoc.rb', line 208

def initialize
  super
  @options = YardocOptions.new
  @options.reset_defaults
  @visibilities = [:public]
  @apis = []
  @assets = {}
  @excluded = []
  @files = []
  @hidden_tags = []
  @use_cache = false
  @use_yardopts_file = true
  @use_document_file = true
  @generate = true
  @options_file = DEFAULT_YARDOPTS_FILE
  @statistics = true
  @list = false
  @save_yardoc = true
  @has_markup = false

  if defined?(::Encoding) && ::Encoding.respond_to?(:default_external=)
    ::Encoding.default_external, ::Encoding.default_internal = 'utf-8', 'utf-8'
  end
end

Instance Attribute Details

#apis ⇒ Array<String>

Keep track of which APIs are to be shown

Returns:

Since:

  • 0.8.1



189
190
191
 
# File 'lib/yard/cli/yardoc.rb', line 189

def apis
  @apis
end

#assets ⇒ Array<String>

Returns a list of assets to copy after generation.

Returns:

  • (Array<String>) —

    a list of assets to copy after generation

Since:

  • 0.6.0



201
202
203
 
# File 'lib/yard/cli/yardoc.rb', line 201

def assets
  @assets
end

#excluded ⇒ Array<String>

Returns list of excluded paths (regexp matches).

Returns:

  • (Array<String>) —

    list of excluded paths (regexp matches)

Since:

  • 0.5.3



154
155
156
 
# File 'lib/yard/cli/yardoc.rb', line 154

def excluded
  @excluded
end

#files ⇒ Array<String>

Returns list of Ruby source files to process.

Returns:

  • (Array<String>) —

    list of Ruby source files to process

Since:

  • 0.2.1



150
151
152
 
# File 'lib/yard/cli/yardoc.rb', line 150

def files
  @files
end

#generate ⇒ Boolean

Returns whether to generate output.

Returns:

  • (Boolean) —

    whether to generate output

Since:

  • 0.2.1



171
172
173
 
# File 'lib/yard/cli/yardoc.rb', line 171

def generate
  @generate
end

#has_markup ⇒ Boolean

Returns whether markup option was specified.

Returns:

  • (Boolean) —

    whether markup option was specified

Since:

  • 0.7.0



205
206
207
 
# File 'lib/yard/cli/yardoc.rb', line 205

def has_markup
  @has_markup
end

#hidden_tags ⇒ Array<Symbol>

Returns a list of tags to hide from templates.

Returns:

  • (Array<Symbol>) —

    a list of tags to hide from templates

Since:

  • 0.6.0



193
194
195
 
# File 'lib/yard/cli/yardoc.rb', line 193

def hidden_tags
  @hidden_tags
end

#list ⇒ Boolean

Returns whether to print a list of objects.

Returns:

  • (Boolean) —

    whether to print a list of objects

Since:

  • 0.5.5



175
176
177
 
# File 'lib/yard/cli/yardoc.rb', line 175

def list
  @list
end

#options ⇒ Hash (readonly)

Returns the hash of options passed to the template.

Returns:

  • (Hash) —

    the hash of options passed to the template.

See Also:

  • Templates::Engine#render

Since:

  • 0.2.1



147
148
149
 
# File 'lib/yard/cli/yardoc.rb', line 147

def options
  @options
end

#options_file ⇒ String

The options file name (defaults to DEFAULT_YARDOPTS_FILE)

Returns:

  • (String) —

    the filename to load extra options from

Since:

  • 0.2.1



179
180
181
 
# File 'lib/yard/cli/yardoc.rb', line 179

def options_file
  @options_file
end

#save_yardoc ⇒ Boolean

Returns whether objects should be serialized to .yardoc db.

Returns:

  • (Boolean) —

    whether objects should be serialized to .yardoc db

Since:

  • 0.2.1



168
169
170
 
# File 'lib/yard/cli/yardoc.rb', line 168

def save_yardoc
  @save_yardoc
end

#statistics ⇒ Boolean

Returns whether to print statistics after parsing.

Returns:

  • (Boolean) —

    whether to print statistics after parsing

Since:

  • 0.6.0



197
198
199
 
# File 'lib/yard/cli/yardoc.rb', line 197

def statistics
  @statistics
end

#use_cache ⇒ Boolean

Returns whether to use the existing yardoc db if the .yardoc already exists. Also makes use of file checksums to parse only changed files.

Returns:

  • (Boolean) —

    whether to use the existing yardoc db if the .yardoc already exists. Also makes use of file checksums to parse only changed files.

Since:

  • 0.2.1



159
160
161
 
# File 'lib/yard/cli/yardoc.rb', line 159

def use_cache
  @use_cache
end

#use_document_file ⇒ Boolean

Returns whether to parse options from .document.

Returns:

  • (Boolean) —

    whether to parse options from .document

Since:

  • 0.2.1



165
166
167
 
# File 'lib/yard/cli/yardoc.rb', line 165

def use_document_file
  @use_document_file
end

#use_yardopts_file ⇒ Boolean

Returns whether to parse options from .yardopts.

Returns:

  • (Boolean) —

    whether to parse options from .yardopts

Since:

  • 0.2.1



162
163
164
 
# File 'lib/yard/cli/yardoc.rb', line 162

def use_yardopts_file
  @use_yardopts_file
end

#visibilities ⇒ Array<Symbol>

Keep track of which visibilities are to be shown

Returns:

  • (Array<Symbol>) —

    a list of visibilities

Since:

  • 0.5.6



184
185
186
 
# File 'lib/yard/cli/yardoc.rb', line 184

def visibilities
  @visibilities
end

Instance Method Details

#all_objects ⇒ Array<CodeObjects::Base>

Deprecated.

To hide methods use the @private tag instead.

The list of all objects to process. Override this method to change which objects YARD should generate documentation for.

Returns:

Since:

  • 0.2.1



318
319
320
 
# File 'lib/yard/cli/yardoc.rb', line 318

def all_objects
  Registry.all(:root, :module, :class)
end

#description ⇒ Object

Since:

  • 0.2.1



233
234
235
 
# File 'lib/yard/cli/yardoc.rb', line 233

def description
  "Generates documentation"
end

#parse_arguments(*args) ⇒ Boolean

Parses commandline arguments

Parameters:

Returns:

  • (Boolean) —

    whether or not arguments are valid

Since:

  • 0.5.6



278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
 
# File 'lib/yard/cli/yardoc.rb', line 278

def parse_arguments(*args)
  parse_yardopts_options(*args)

  # Parse files and then command line arguments
  optparse(*support_rdoc_document_file!) if use_document_file
  optparse(*yardopts) if use_yardopts_file
  optparse(*args)

  # Last minute modifications
  self.files = ['{lib,app}/**/*.rb', 'ext/**/*.c'] if self.files.empty?
  self.files.delete_if {|x| x =~ /\A\s*\Z/ } # remove empty ones
  readme = Dir.glob('README*').first
  readme ||= Dir.glob(files.first).first if options.onefile
  options.readme ||= CodeObjects::ExtraFileObject.new(readme) if readme
  options.files.unshift(options.readme).uniq! if options.readme

  Tags::Library.visible_tags -= hidden_tags
  add_visibility_verifier
  add_api_verifier

  # US-ASCII is invalid encoding for onefile
  if defined?(::Encoding) && options.onefile
    if ::Encoding.default_internal == ::Encoding::US_ASCII
      log.warn "--one-file is not compatible with US-ASCII encoding, using ASCII-8BIT"
      ::Encoding.default_external, ::Encoding.default_internal = ['ascii-8bit'] * 2
    end
  end

  if generate && !verify_markup_options
    false
  else
    true
  end
end

#run(*args) ⇒ void

This method returns an undefined value.

Runs the commandline utility, parsing arguments and generating output if set.

Parameters:

Since:

  • 0.2.1



243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/yard/cli/yardoc.rb', line 243

def run(*args)
  if args.size == 0 || !args.first.nil?
    # fail early if arguments are not valid
    return unless parse_arguments(*args)
  end

  checksums = nil
  if use_cache
    Registry.load
    checksums = Registry.checksums.dup
  end
  YARD.parse(files, excluded)
  Registry.save(use_cache) if save_yardoc

  if generate
    run_generate(checksums)
    copy_assets
  elsif list
    print_list
  end

  if !list && statistics && log.level < Logger::ERROR
    Registry.load_all
    log.enter_level(Logger::ERROR) do
      Stats.new(false).run(*args)
    end
  end

  true
end

#yardopts ⇒ Array<String>

Parses the .yardopts file for default yard options

Returns:

  • (Array<String>) —

    an array of options parsed from .yardopts

Since:

  • 0.2.1



324
325
326
327
328
329
 
# File 'lib/yard/cli/yardoc.rb', line 324

def yardopts
  return [] unless use_yardopts_file
  File.read_binary(options_file).shell_split
rescue Errno::ENOENT
  []
end