Parent

Class/Module Index [+]

Quicksearch

YARD::Config

This class maintains all system-wide configuration for YARD and handles the loading of plugins. To access options call {options}, and to load a plugin use {load_plugin}. All other public methods are used by YARD during load time.

User Configuration Files

Persistent user configuration files can be stored in the file +~/.yard/config+, which is read when YARD first loads. The file should be formatted as YAML, and should contain a map of keys and values.

Although you can specify any key-value mapping in the configuration file, YARD defines special keys specified in {DEFAULT_CONFIG_OPTIONS}.

An example of a configuration file is listed below:

!!!yaml
load_plugins: true # Auto-load plugins when YARD starts
ignored_plugins:
  - yard-broken
  - broken2 # yard- prefix not necessary
autoload_plugins:
  - yard-rspec

Automatic Loading of Plugins

YARD 0.6.2 will no longer automatically load all plugins by default. This option can be reset by setting 'load_plugins' to true in the configuration file. In addition, you can specify a set of specific plugins to load on load through the 'autoload_plugins' list setting. This setting is independent of the 'load_plugins' value and will always be processed.

Ignored Plugins File

YARD 0.5 and below used a +~/.yard/ignored_plugins+ file to specify plugins to be ignored at load time. Ignored plugins in 0.6.2 and above should now be specified in the main configuration file, though YARD will support the ignored_plugins file until 0.7.x.

Safe Mode

YARD supports running in safe-mode. By doing this, it will avoid executing any user code such as require files or queries. Plugins will still be loaded with safe mode on, because plugins are properly namespaced with a 'yard-' prefix, must be installed as a gem, and therefore cannot be touched by the user. To specify safe mode, use the safe_mode key.

Plugin Specific Configuration

Additional settings can be defined within the configuration file specifically to provide configuration for a plugin. A plugin that utilizes the YARD configuration is strongly encouraged to utilize namespacing of their configuration content.

!!!yaml
load_plugins: true # Auto-load plugins when YARD starts
ignored_plugins:
  - yard-broken
  - broken2 # yard- prefix not necessary
autoload_plugins:
  - yard-rspec
# Plugin Specific Configuration
yard-sample-plugin:
  show-results-inline: true

As the configuration is available system wide, it can be accessed within the plugin code.

if YARD::Config.options['yard-sample-plugin'] and
  YARD::Config.options['yard-sample-plugin']['show-results-inline']
  # ... perform the action that places the results inline ...
else
  # ... do the default behavior of not showing the results inline ...
end

When accessing the configuration, be aware that this file is user managed so configuration keys and values may not be present. Make no assumptions and instead ensure that you check for the existence of keys before proceeding to retrieve values.

@since 0.6.2 @see options

Constants

CONFIG_DIR

The location where YARD stores user-specific settings

CONFIG_FILE

The main configuration YAML file.

DEFAULT_CONFIG_OPTIONS

Default configuration options

IGNORED_PLUGINS

File listing all ignored plugins @deprecated Set `ignored_plugins` in the {CONFIG_FILE} instead.

YARD_PLUGIN_PREFIX

The prefix used for YARD plugins. Name your gem with this prefix to allow it to be used as a plugin.

Attributes

options[RW]

The system-wide configuration options for YARD @return [SymbolHash] a map a key-value pair settings. @see DEFAULT_CONFIG_OPTIONS

Public Class Methods

load() click to toggle source

Loads settings from {CONFIG_FILE}. This method is called by YARD at load time and should not be called by the user. @return [void]

# File lib/yard/config.rb, line 118
def self.load
  self.options = SymbolHash.new(false)
  options.update(DEFAULT_CONFIG_OPTIONS)
  options.update(read_config_file)
  load_commandline_safemode
  add_ignored_plugins_file
  translate_plugin_names
  load_plugins
rescue
  log.error "Invalid configuration file, using default options."
  options.update(DEFAULT_CONFIG_OPTIONS)
end
load_plugin(name) click to toggle source

Loads an individual plugin by name. It is not necessary to include the yard- plugin prefix here.

@param [String] name the name of the plugin (with or without yard- prefix) @return [Boolean] whether the plugin was successfully loaded

# File lib/yard/config.rb, line 154
def self.load_plugin(name)
  name = translate_plugin_name(name)
  return false if options[:ignored_plugins].include?(name)
  return false if name =~ /^yard-doc-/
  log.debug "Loading plugin '#{name}'..."
  require name
  true
rescue LoadError => e
  load_plugin_failed(name, e)
end
load_plugins() click to toggle source

Loads gems that match the name 'yard-*' (recommended) or 'yard_*' except those listed in +~/.yard/ignored_plugins+. This is called immediately after YARD is loaded to allow plugin support.

@return [Boolean] true if all plugins loaded successfully, false otherwise.

# File lib/yard/config.rb, line 143
def self.load_plugins
  load_gem_plugins &&
    load_autoload_plugins &&
    load_commandline_plugins ? true : false
end
save() click to toggle source

Saves settings to {CONFIG_FILE}. @return [void]

# File lib/yard/config.rb, line 133
def self.save
  require 'yaml'
  File.open(CONFIG_FILE, 'w') {|f| f.write(YAML.dump(options)) }
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.