Class Gem::DocManager
In: lib/rubygems/doc_manager.rb
Parent: Object

The documentation manager generates RDoc and RI for RubyGems.

Methods

Included Modules

Gem::UserInteraction

Public Class methods

[Source]

    # File lib/rubygems/doc_manager.rb, line 19
19:   def self.configured_args
20:     @configured_args ||= []
21:   end

[Source]

    # File lib/rubygems/doc_manager.rb, line 23
23:   def self.configured_args=(args)
24:     case args
25:     when Array
26:       @configured_args = args
27:     when String
28:       @configured_args = args.split
29:     end
30:   end

Load RDoc from a gem if it is available, otherwise from Ruby‘s stdlib

[Source]

    # File lib/rubygems/doc_manager.rb, line 35
35:   def self.load_rdoc
36:     begin
37:       gem 'rdoc'
38:     rescue Gem::LoadError
39:       # use built-in RDoc
40:     end
41: 
42:     begin
43:       require 'rdoc/rdoc'
44:     rescue LoadError => e
45:       raise Gem::DocumentError,
46:           "ERROR: RDoc documentation generator not installed!"
47:     end
48:   end

Create a document manager for spec. rdoc_args contains arguments for RDoc (template etc.) as a String.

[Source]

    # File lib/rubygems/doc_manager.rb, line 76
76:   def initialize(spec, rdoc_args="")
77:     @spec = spec
78:     @doc_dir = File.join(spec.installation_path, "doc", spec.full_name)
79:     @rdoc_args = rdoc_args.nil? ? [] : rdoc_args.split
80:   end

Updates the RI cache for RDoc 2 if it is installed

[Source]

    # File lib/rubygems/doc_manager.rb, line 53
53:   def self.update_ri_cache
54:     load_rdoc rescue return
55: 
56:     return unless defined? RDoc::VERSION # RDoc 1 does not have VERSION
57: 
58:     require 'rdoc/ri/driver'
59: 
60:     options = {
61:       :use_cache => true,
62:       :use_system => true,
63:       :use_site => true,
64:       :use_home => true,
65:       :use_gems => true,
66:       :formatter => RDoc::RI::Formatter,
67:     }
68: 
69:     driver = RDoc::RI::Driver.new(options).class_cache
70:   end

Public Instance methods

Generate the RDoc documents for this gem spec.

Note that if both RI and RDoc documents are generated from the same process, the RI docs should be done first (a likely bug in RDoc will cause RI docs generation to fail if run after RDoc).

[Source]

     # File lib/rubygems/doc_manager.rb, line 112
112:   def generate_rdoc
113:     if @spec.has_rdoc then
114:       setup_rdoc
115:       install_rdoc
116:     end
117: 
118:     FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
119:   end

Generate the RI documents for this gem spec.

Note that if both RI and RDoc documents are generated from the same process, the RI docs should be done first (a likely bug in RDoc will cause RI docs generation to fail if run after RDoc).

[Source]

     # File lib/rubygems/doc_manager.rb, line 96
 96:   def generate_ri
 97:     if @spec.has_rdoc then
 98:       setup_rdoc
 99:       install_ri # RDoc bug, ri goes first
100:     end
101: 
102:     FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
103:   end

Generate and install RDoc into the documentation directory

[Source]

     # File lib/rubygems/doc_manager.rb, line 124
124:   def install_rdoc
125:     rdoc_dir = File.join @doc_dir, 'rdoc'
126: 
127:     FileUtils.rm_rf rdoc_dir
128: 
129:     say "Installing RDoc documentation for #{@spec.full_name}..."
130:     run_rdoc '--op', rdoc_dir
131:   end

Generate and install RI into the documentation directory

[Source]

     # File lib/rubygems/doc_manager.rb, line 136
136:   def install_ri
137:     ri_dir = File.join @doc_dir, 'ri'
138: 
139:     FileUtils.rm_rf ri_dir
140: 
141:     say "Installing ri documentation for #{@spec.full_name}..."
142:     run_rdoc '--ri', '--op', ri_dir
143:   end

Is the RDoc documentation installed?

[Source]

    # File lib/rubygems/doc_manager.rb, line 85
85:   def rdoc_installed?
86:     File.exist?(File.join(@doc_dir, "rdoc"))
87:   end

Run RDoc with args, which is an ARGV style argument list

[Source]

     # File lib/rubygems/doc_manager.rb, line 148
148:   def run_rdoc(*args)
149:     args << @spec.rdoc_options
150:     args << self.class.configured_args
151:     args << '--quiet'
152:     args << @spec.require_paths.clone
153:     args << @spec.extra_rdoc_files
154:     args = args.flatten.map do |arg| arg.to_s end
155: 
156:     r = RDoc::RDoc.new
157: 
158:     old_pwd = Dir.pwd
159:     Dir.chdir(@spec.full_gem_path)
160:     begin
161:       r.document args
162:     rescue Errno::EACCES => e
163:       dirname = File.dirname e.message.split("-")[1].strip
164:       raise Gem::FilePermissionError.new(dirname)
165:     rescue RuntimeError => ex
166:       alert_error "While generating documentation for #{@spec.full_name}"
167:       ui.errs.puts "... MESSAGE:   #{ex}"
168:       ui.errs.puts "... RDOC args: #{args.join(' ')}"
169:       ui.errs.puts "\t#{ex.backtrace.join "\n\t"}" if
170:       Gem.configuration.backtrace
171:       ui.errs.puts "(continuing with the rest of the installation)"
172:     ensure
173:       Dir.chdir(old_pwd)
174:     end
175:   end

[Source]

     # File lib/rubygems/doc_manager.rb, line 177
177:   def setup_rdoc
178:     if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then
179:       raise Gem::FilePermissionError.new(@doc_dir)
180:     end
181: 
182:     FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
183: 
184:     self.class.load_rdoc
185:   end

Remove RDoc and RI documentation

[Source]

     # File lib/rubygems/doc_manager.rb, line 190
190:   def uninstall_doc
191:     raise Gem::FilePermissionError.new(@spec.installation_path) unless
192:     File.writable? @spec.installation_path
193: 
194:     original_name = [
195:       @spec.name, @spec.version, @spec.original_platform].join '-'
196: 
197:       doc_dir = File.join @spec.installation_path, 'doc', @spec.full_name
198:       unless File.directory? doc_dir then
199:         doc_dir = File.join @spec.installation_path, 'doc', original_name
200:       end
201: 
202:       FileUtils.rm_rf doc_dir
203: 
204:       ri_dir = File.join @spec.installation_path, 'ri', @spec.full_name
205: 
206:       unless File.directory? ri_dir then
207:         ri_dir = File.join @spec.installation_path, 'ri', original_name
208:       end
209: 
210:       FileUtils.rm_rf ri_dir
211:   end

[Validate]