Class: YARD::Config

Inherits:
Object
  • Object
show all
Defined in:
lib/yard/config.rb

Overview

This class maintains all system-wide configuration for YARD and handles the loading of plugins. To access options call Config.options, and to load a plugin use Config.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:

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.

See Also:

Since:

  • 0.6.2

Constant Summary collapse

CONFIG_DIR =

The location where YARD stores user-specific settings

Since:

  • 0.6.2

File.expand_path('~/.yard')
CONFIG_FILE =

The main configuration YAML file.

Since:

  • 0.6.2

File.join(CONFIG_DIR, 'config')
IGNORED_PLUGINS =
Deprecated.

Set ‘ignored_plugins` in the CONFIG_FILE instead.

File listing all ignored plugins

Since:

  • 0.6.2

File.join(CONFIG_DIR, 'ignored_plugins')
DEFAULT_CONFIG_OPTIONS =

Default configuration options

Since:

  • 0.6.2

{
  :load_plugins => false,   # Whether to load plugins automatically with YARD
  :ignored_plugins => [],   # A list of ignored plugins by name
  :autoload_plugins => [],  # A list of plugins to be automatically loaded
  :safe_mode => false       # Does not execute or eval any user-level code
}
YARD_PLUGIN_PREFIX =

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

Since:

  • 0.6.2

/^yard[-_]/

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.options ⇒ SymbolHash

The system-wide configuration options for YARD

Returns:

  • (SymbolHash) —

    a map a key-value pair settings.

See Also:

Since:

  • 0.6.2



56
57
58
 
# File 'lib/yard/config.rb', line 56

def options
  @options
end

Class Method Details

.load ⇒ void

This method returns an undefined value.

Loads settings from CONFIG_FILE. This method is called by YARD at load time and should not be called by the user.

Since:

  • 0.6.2



84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/yard/config.rb', line 84

def self.load
  self.options = SymbolHash.new(false)
  options.update(DEFAULT_CONFIG_OPTIONS)
  options.update(read_config_file)
  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) ⇒ Boolean

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

Parameters:

  • name (String) —

    the name of the plugin (with or without yard- prefix)

Returns:

  • (Boolean) —

    whether the plugin was successfully loaded

Since:

  • 0.6.2



119
120
121
122
123
124
125
126
127
128
 
# File 'lib/yard/config.rb', line 119

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 ⇒ Boolean

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.

Returns:

  • (Boolean) —

    true if all plugins loaded successfully, false otherwise.

Since:

  • 0.6.2



108
109
110
111
112
 
# File 'lib/yard/config.rb', line 108

def self.load_plugins
  load_gem_plugins &&
    load_autoload_plugins &&
    load_commandline_plugins ? true : false
end

.save ⇒ void

This method returns an undefined value.

Saves settings to CONFIG_FILE.

Since:

  • 0.6.2



98
99
100
101
 
# File 'lib/yard/config.rb', line 98

def self.save
  require 'yaml'
  File.open(CONFIG_FILE, 'w') {|f| f.write(YAML.dump(options)) }
end