Class: YARD::CLI::Yardoc
- Inherits:
-
YardoptsCommand
- Object
- Command
- YardoptsCommand
- YARD::CLI::Yardoc
- 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).
Constant Summary
Instance Attribute Summary (collapse)
-
- (Array<String>) apis
Keep track of which APIs are to be shown.
-
- (Array<String>) assets
A list of assets to copy after generation.
-
- (Array<String>) excluded
List of excluded paths (regexp matches).
-
- (Array<String>) files
List of Ruby source files to process.
-
- (Boolean) generate
Whether to generate output.
-
- (Boolean) has_markup
Whether markup option was specified.
-
- (Array<String>) hidden_apis
Keep track of which APIs are to be hidden.
-
- (Array<Symbol>) hidden_tags
A list of tags to hide from templates.
-
- (Boolean) list
Whether to print a list of objects.
-
- (Hash) options
readonly
The hash of options passed to the template.
-
- (String) options_file
inherited
from YardoptsCommand
The options file name (defaults to YARD::CLI::YardoptsCommand::DEFAULT_YARDOPTS_FILE).
-
- (Boolean) save_yardoc
Whether objects should be serialized to .yardoc db.
-
- (Boolean) statistics
Whether to print statistics after parsing.
-
- (Boolean) use_cache
Whether to use the existing yardoc db if the .yardoc already exists.
-
- (Boolean) use_document_file
inherited
from YardoptsCommand
Whether to parse options from .document.
-
- (Boolean) use_yardopts_file
inherited
from YardoptsCommand
Whether to parse options from .yardopts.
-
- (Array<Symbol>) visibilities
Keep track of which visibilities are to be shown.
Instance Method Summary (collapse)
-
- (Array<CodeObjects::Base>) all_objects
deprecated
Deprecated.
To hide methods use the @private tag instead.
- - (Object) description
-
- (Yardoc) initialize
constructor
Creates a new instance of the commandline utility.
-
- (Boolean) parse_arguments(*args)
Parses commandline arguments.
-
- (void) run(*args)
Runs the commandline utility, parsing arguments and generating output if set.
Constructor Details
- (Yardoc) initialize
Creates a new instance of the commandline utility
200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 |
# File 'lib/yard/cli/yardoc.rb', line 200 def initialize super @options = YardocOptions.new @options.reset_defaults @visibilities = [:public] @apis = [] @hidden_apis = [] @assets = {} @excluded = [] @files = [] @hidden_tags = [] @use_cache = false @generate = true @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
- (Array<String>) apis
Keep track of which APIs are to be shown
176 177 178 |
# File 'lib/yard/cli/yardoc.rb', line 176 def apis @apis end |
- (Array<String>) assets
Returns a list of assets to copy after generation
193 194 195 |
# File 'lib/yard/cli/yardoc.rb', line 193 def assets @assets end |
- (Array<String>) excluded
Returns list of excluded paths (regexp matches)
151 152 153 |
# File 'lib/yard/cli/yardoc.rb', line 151 def excluded @excluded end |
- (Array<String>) files
Returns list of Ruby source files to process
147 148 149 |
# File 'lib/yard/cli/yardoc.rb', line 147 def files @files end |
- (Boolean) generate
Returns whether to generate output
162 163 164 |
# File 'lib/yard/cli/yardoc.rb', line 162 def generate @generate end |
- (Boolean) has_markup
Returns whether markup option was specified
197 198 199 |
# File 'lib/yard/cli/yardoc.rb', line 197 def has_markup @has_markup end |
- (Array<String>) hidden_apis
Keep track of which APIs are to be hidden
181 182 183 |
# File 'lib/yard/cli/yardoc.rb', line 181 def hidden_apis @hidden_apis end |
- (Array<Symbol>) hidden_tags
Returns a list of tags to hide from templates
185 186 187 |
# File 'lib/yard/cli/yardoc.rb', line 185 def @hidden_tags end |
- (Boolean) list
Returns whether to print a list of objects
166 167 168 |
# File 'lib/yard/cli/yardoc.rb', line 166 def list @list end |
- (Hash) options (readonly)
Returns the hash of options passed to the template.
144 145 146 |
# File 'lib/yard/cli/yardoc.rb', line 144 def @options end |
- (String) options_file Originally defined in class YardoptsCommand
The options file name (defaults to DEFAULT_YARDOPTS_FILE)
- (Boolean) save_yardoc
Returns whether objects should be serialized to .yardoc db
159 160 161 |
# File 'lib/yard/cli/yardoc.rb', line 159 def save_yardoc @save_yardoc end |
- (Boolean) statistics
Returns whether to print statistics after parsing
189 190 191 |
# File 'lib/yard/cli/yardoc.rb', line 189 def statistics @statistics end |
- (Boolean) use_cache
Returns whether to use the existing yardoc db if the .yardoc already exists. Also makes use of file checksums to parse only changed files.
156 157 158 |
# File 'lib/yard/cli/yardoc.rb', line 156 def use_cache @use_cache end |
- (Boolean) use_document_file Originally defined in class YardoptsCommand
Returns whether to parse options from .document
- (Boolean) use_yardopts_file Originally defined in class YardoptsCommand
Returns whether to parse options from .yardopts
- (Array<Symbol>) visibilities
Keep track of which visibilities are to be shown
171 172 173 |
# File 'lib/yard/cli/yardoc.rb', line 171 def visibilities @visibilities end |
Instance Method Details
- (Array<CodeObjects::Base>) all_objects
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.
308 309 310 |
# File 'lib/yard/cli/yardoc.rb', line 308 def all_objects Registry.all(:root, :module, :class) end |
- (Object) description
223 224 225 |
# File 'lib/yard/cli/yardoc.rb', line 223 def description "Generates documentation" end |
- (Boolean) parse_arguments(*args)
Parses commandline arguments
271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 |
# File 'lib/yard/cli/yardoc.rb', line 271 def parse_arguments(*args) super(*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 .onefile .readme ||= CodeObjects::ExtraFileObject.new(readme) if readme .files.unshift(.readme).uniq! if .readme Tags::Library. -= add_visibility_verifier add_api_verifier apply_locale # US-ASCII is invalid encoding for onefile if defined?(::Encoding) && .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 && ! false else true end end |
- (void) run(*args)
This method returns an undefined value.
Runs the commandline utility, parsing arguments and generating output if set.
233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 |
# File 'lib/yard/cli/yardoc.rb', line 233 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 |