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.
Main usage for this command is:
$ yardoc [options] [source_files [- extra_files]]
See +yardoc --help+ for details on valid options.
.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.
--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.
--tag
)YARD allows specification of {file:docs/Tags.md meta-data tags} programmatically via the {YARD::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.
.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
).
@since 0.2.1 @see Verifier
The configuration filename to load extra options from
Keep track of which APIs are to be shown @return [Array<String>] a list of APIs @since 0.8.1
@return [Array<String>] a list of assets to copy after generation @since 0.6.0
@return [Array<String>] list of excluded paths (regexp matches) @since 0.5.3
@return [Array<String>] list of Ruby source files to process
@return [Boolean] whether to generate output
@return [Boolean] whether markup option was specified @since 0.7.0
@return [Boolean] whether to print a list of objects @since 0.5.5
@return [Hash] the hash of options passed to the template. @see Templates::Engine#render
The options file name (defaults to {DEFAULT_YARDOPTS_FILE}) @return [String] the filename to load extra options from
@return [Boolean] whether objects should be serialized to .yardoc db
@return [Boolean] whether to print statistics after parsing @since 0.6.0
@return [Boolean] whether to use the existing yardoc db if the
.yardoc already exists. Also makes use of file checksums to parse only changed files.
@return [Boolean] whether to parse options from .document
@return [Boolean] whether to parse options from .yardopts
Keep track of which visibilities are to be shown @return [Array<Symbol>] a list of visibilities @since 0.5.6
Creates a new instance of the commandline utility
# 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
The list of all objects to process. Override this method to change which objects YARD should generate documentation for.
@deprecated To hide methods use the +@private+ tag instead. @return [Array<CodeObjects::Base>] a list of code objects to process
# File lib/yard/cli/yardoc.rb, line 321 def all_objects Registry.all(:root, :module, :class) end
# File lib/yard/cli/yardoc.rb, line 233 def description "Generates documentation" end
Parses commandline arguments @param [Array<String>] args the list of arguments @return [Boolean] whether or not arguments are valid @since 0.5.6
# File lib/yard/cli/yardoc.rb, line 281 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 =~ %r\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
Runs the commandline utility, parsing arguments and generating output if set.
@param [Array<String>] args the list of arguments. If the list only
contains a single nil value, skip calling of {#parse_arguments}
@return [void]
# File lib/yard/cli/yardoc.rb, line 243 def run(*args) log.show_progress = true 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 ensure log.show_progress = false end
Parses the .yardopts file for default yard options @return [Array<String>] an array of options parsed from .yardopts
# File lib/yard/cli/yardoc.rb, line 327 def yardopts return [] unless use_yardopts_file File.read_binary(options_file).shell_split rescue Errno::ENOENT [] end