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 [] [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
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 yard help doc 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
).
Instance Attribute Summary collapse
-
#apis ⇒ Array<String>
Keep track of which APIs are to be shown.
-
#assets ⇒ Array<String>
A list of assets to copy after generation.
-
#excluded ⇒ Array<String>
List of excluded paths (regexp matches).
-
#fail_on_warning ⇒ Boolean
Whether yard exits with error status code if a warning occurs.
-
#files ⇒ Array<String>
List of Ruby source files to process.
-
#generate ⇒ Boolean
Whether to generate output.
-
#has_markup ⇒ Boolean
Whether markup option was specified.
-
#hidden_apis ⇒ Array<String>
Keep track of which APIs are to be hidden.
-
#hidden_tags ⇒ Array<Symbol>
A list of tags to hide from templates.
-
#list ⇒ Boolean
Whether to print a list of objects.
-
#options ⇒ Hash
readonly
The hash of options passed to the template.
-
#save_yardoc ⇒ Boolean
Whether objects should be serialized to .yardoc db.
-
#statistics ⇒ Boolean
Whether to print statistics after parsing.
-
#use_cache ⇒ Boolean
Whether to use the existing yardoc db if the .yardoc already exists.
-
#visibilities ⇒ Array<Symbol>
Keep track of which visibilities are to be shown.
Instance Method Summary collapse
-
#all_objects ⇒ Array<CodeObjects::Base>
deprecated
Deprecated.
To hide methods use the @private tag instead.
- #description ⇒ Object
-
#initialize ⇒ Yardoc
constructor
Creates a new instance of the commandline utility.
-
#parse_arguments(*args) ⇒ Boolean
Parses commandline arguments.
-
#run(*args) ⇒ void
Runs the commandline utility, parsing arguments and generating output if set.
Constructor Details
#initialize ⇒ Yardoc
Creates a new instance of the commandline utility
207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 |
# File 'lib/yard/cli/yardoc.rb', line 207 def initialize super = YardocOptions.new .reset_defaults @visibilities = [:public] @apis = [] @hidden_apis = [] @assets = {} @excluded = [] @files = [] = [] @use_cache = false @generate = true @statistics = true @list = false @save_yardoc = true @has_markup = false @fail_on_warning = false if defined?(::Encoding) && ::Encoding.respond_to?(:default_external=) utf8 = ::Encoding.find('utf-8') ::Encoding.default_external = utf8 unless ::Encoding.default_external == utf8 ::Encoding.default_internal = utf8 unless ::Encoding.default_internal == utf8 end end |
Instance Attribute Details
#apis ⇒ Array<String>
Keep track of which APIs are to be shown
180 181 182 |
# File 'lib/yard/cli/yardoc.rb', line 180 def apis @apis end |
#assets ⇒ Array<String>
Returns a list of assets to copy after generation.
197 198 199 |
# File 'lib/yard/cli/yardoc.rb', line 197 def assets @assets end |
#excluded ⇒ Array<String>
Returns list of excluded paths (regexp matches).
155 156 157 |
# File 'lib/yard/cli/yardoc.rb', line 155 def excluded @excluded end |
#fail_on_warning ⇒ Boolean
Returns whether yard exits with error status code if a warning occurs.
204 205 206 |
# File 'lib/yard/cli/yardoc.rb', line 204 def fail_on_warning @fail_on_warning end |
#files ⇒ Array<String>
Returns list of Ruby source files to process.
151 152 153 |
# File 'lib/yard/cli/yardoc.rb', line 151 def files @files end |
#generate ⇒ Boolean
Returns whether to generate output.
166 167 168 |
# File 'lib/yard/cli/yardoc.rb', line 166 def generate @generate end |
#has_markup ⇒ Boolean
Returns whether markup option was specified.
201 202 203 |
# File 'lib/yard/cli/yardoc.rb', line 201 def has_markup @has_markup end |
#hidden_apis ⇒ Array<String>
Keep track of which APIs are to be hidden
185 186 187 |
# File 'lib/yard/cli/yardoc.rb', line 185 def hidden_apis @hidden_apis end |
#hidden_tags ⇒ Array<Symbol>
Returns a list of tags to hide from templates.
189 190 191 |
# File 'lib/yard/cli/yardoc.rb', line 189 def end |
#list ⇒ Boolean
Returns whether to print a list of objects.
170 171 172 |
# File 'lib/yard/cli/yardoc.rb', line 170 def list @list end |
#options ⇒ Hash (readonly)
Returns the hash of options passed to the template.
148 149 150 |
# File 'lib/yard/cli/yardoc.rb', line 148 def end |
#save_yardoc ⇒ Boolean
Returns whether objects should be serialized to .yardoc db.
163 164 165 |
# File 'lib/yard/cli/yardoc.rb', line 163 def save_yardoc @save_yardoc end |
#statistics ⇒ Boolean
Returns whether to print statistics after parsing.
193 194 195 |
# File 'lib/yard/cli/yardoc.rb', line 193 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.
160 161 162 |
# File 'lib/yard/cli/yardoc.rb', line 160 def use_cache @use_cache end |
#visibilities ⇒ Array<Symbol>
Keep track of which visibilities are to be shown
175 176 177 |
# File 'lib/yard/cli/yardoc.rb', line 175 def visibilities @visibilities end |
Instance Method Details
#all_objects ⇒ Array<CodeObjects::Base>
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.
330 331 332 |
# File 'lib/yard/cli/yardoc.rb', line 330 def all_objects Registry.all(:root, :module, :class) end |
#description ⇒ Object
234 235 236 |
# File 'lib/yard/cli/yardoc.rb', line 234 def description "Generates documentation" end |
#parse_arguments(*args) ⇒ Boolean
Parses commandline arguments
291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 |
# File 'lib/yard/cli/yardoc.rb', line 291 def parse_arguments(*args) super(*args) # Last minute modifications self.files = Parser::SourceParser::DEFAULT_PATH_GLOB if files.empty? files.delete_if {|x| x =~ /\A\s*\Z/ } # remove empty ones readme = Dir.glob('README{,*[^~]}'). select {|f| extra_file_valid?(f)}. sort_by {|r| [r.count('.'), r.index('.'), r] }.first readme ||= Dir.glob(files.first).first if .onefile && !files.empty? .readme ||= CodeObjects::ExtraFileObject.new(readme) if readme && extra_file_valid?(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 |
#run(*args) ⇒ void
This method returns an undefined value.
Runs the commandline utility, parsing arguments and generating output if set.
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 273 274 275 276 277 278 279 280 281 282 283 284 285 |
# File 'lib/yard/cli/yardoc.rb', line 244 def run(*args) log.show_progress = true if args.empty? || !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 if save_yardoc Registry.lock_for_writing do YARD.parse(files, excluded) Registry.save(use_cache) end else YARD.parse(files, excluded) end 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 abort if fail_on_warning && log.warned true ensure log.show_progress = false end |