Module: RDoc::RI::Paths

Defined in:
lib/rdoc/ri/paths.rb

Overview

The directories where ri data lives. Paths can be enumerated via ::each, or queried individually via ::system_dir, ::site_dir, ::home_dir and ::gem_dir.

Constant Summary collapse

BASE = 
if RbConfig::CONFIG.key? 'ridir' then
  File.join RbConfig::CONFIG['ridir'], version
else
  File.join RbConfig::CONFIG['datadir'], 'ri', version
end
HOMEDIR = 
if homedir then
  File.join homedir, ".rdoc"
end

Class Method Summary collapse

Class Method Details

.each(system = true, site = true, home = true, gems = :latest, *extra_dirs) {|system_dir, :system| ... } ⇒ Object

Iterates over each selected path yielding the directory and type.

Yielded types:

:system

Where Ruby’s ri data is stored. Yielded when system is true

:site

Where ri for installed libraries are stored. Yielded when site is true. Normally no ri data is stored here.

:home

~/.rdoc. Yielded when home is true.

:gem

ri data for an installed gem. Yielded when gems is true.

:extra

ri data directory from the command line. Yielded for each entry in extra_dirs

Yields:



46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/rdoc/ri/paths.rb', line 46

def self.each system = true, site = true, home = true, gems = :latest, *extra_dirs # :yields: directory, type
  return enum_for __method__, system, site, home, gems, *extra_dirs unless
    block_given?

  extra_dirs.each do |dir|
    yield dir, :extra
  end

  yield system_dir,  :system if system
  yield site_dir,    :site   if site
  yield home_dir,    :home   if home and HOMEDIR

  gemdirs(gems).each do |dir|
    yield dir, :gem
  end if gems

  nil
end

.gem_dir(name, version) ⇒ Object

The ri directory for the gem with gem_name.



68
69
70
71
72
73
74
 
# File 'lib/rdoc/ri/paths.rb', line 68

def self.gem_dir name, version
  req = Gem::Requirement.new "= #{version}"

  spec = Gem::Specification.find_by_name name, req

  File.join spec.doc_dir, 'ri'
end

.gemdirs(filter = :latest) ⇒ Object

The latest installed gems’ ri directories. filter can be :all or :latest.

A filter :all includes all versions of gems and includes gems without ri documentation.



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/rdoc/ri/paths.rb', line 83

def self.gemdirs filter = :latest
  require 'rubygems' unless defined?(Gem)

  ri_paths = {}

  all = Gem::Specification.map do |spec|
    [File.join(spec.doc_dir, 'ri'), spec.name, spec.version]
  end

  if filter == :all then
    gemdirs = []

    all.group_by do |_, name, _|
      name
    end.sort_by do |group, _|
      group
    end.map do |group, items|
      items.sort_by do |_, _, version|
        version
      end.reverse_each do |dir,|
        gemdirs << dir
      end
    end

    return gemdirs
  end

  all.each do |dir, name, ver|
    next unless File.exist? dir

    if ri_paths[name].nil? or ver > ri_paths[name].first then
      ri_paths[name] = [ver, name, dir]
    end
  end

  ri_paths.sort_by { |_, (_, name, _)| name }.map { |k, v| v.last }
rescue LoadError
  []
end

.home_dir ⇒ Object

The location of the rdoc data in the user’s home directory.

Like ::system, ri data in the user’s home directory is rare and predates libraries distributed via RubyGems. ri data is rarely generated into this directory.



130
131
132
 
# File 'lib/rdoc/ri/paths.rb', line 130

def self.home_dir
  HOMEDIR
end

.path(system = true, site = true, home = true, gems = :latest, *extra_dirs) ⇒ Object

Returns existing directories from the selected documentation directories as an Array.

See also ::each



140
141
142
143
144
 
# File 'lib/rdoc/ri/paths.rb', line 140

def self.path(system = true, site = true, home = true, gems = :latest, *extra_dirs)
  path = raw_path system, site, home, gems, *extra_dirs

  path.select { |directory| File.directory? directory }
end

.raw_path(system, site, home, gems, *extra_dirs) ⇒ Object

Returns selected documentation directories including nonexistent directories.

See also ::each



152
153
154
155
156
157
158
159
160
 
# File 'lib/rdoc/ri/paths.rb', line 152

def self.raw_path(system, site, home, gems, *extra_dirs)
  path = []

  each(system, site, home, gems, *extra_dirs) do |dir, type|
    path << dir
  end

  path.compact
end

.site_dir ⇒ Object

The location of ri data installed into the site dir.

Historically this was available for documentation installed by ruby libraries predating RubyGems. It is unlikely to contain any content for modern ruby installations.



169
170
171
 
# File 'lib/rdoc/ri/paths.rb', line 169

def self.site_dir
  File.join BASE, 'site'
end

.system_dir ⇒ Object

The location of the built-in ri data.

This data is built automatically when ‘make` is run when ruby is installed. If you did not install ruby by hand you may need to install the documentation yourself. Please consult the documentation for your package manager or ruby installer for details. You can also use the rdoc-data gem to install system ri data for common versions of ruby.



182
183
184
 
# File 'lib/rdoc/ri/paths.rb', line 182

def self.system_dir
  File.join BASE, 'system'
end