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: 
45:       @rdoc_version = if defined? RDoc::VERSION then
46:                         Gem::Version.new RDoc::VERSION
47:                       else
48:                         Gem::Version.new '1.0.1' # HACK parsing is hard
49:                       end
50: 
51:     rescue LoadError => e
52:       raise Gem::DocumentError,
53:           "ERROR: RDoc documentation generator not installed: #{e}"
54:     end
55:   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 87
87:   def initialize(spec, rdoc_args="")
88:     @spec = spec
89:     @doc_dir = File.join(spec.installation_path, "doc", spec.full_name)
90:     @rdoc_args = rdoc_args.nil? ? [] : rdoc_args.split
91:   end

[Source]

    # File lib/rubygems/doc_manager.rb, line 57
57:   def self.rdoc_version
58:     @rdoc_version
59:   end

Updates the RI cache for RDoc 2 if it is installed

[Source]

    # File lib/rubygems/doc_manager.rb, line 64
64:   def self.update_ri_cache
65:     load_rdoc rescue return
66: 
67:     return unless defined? RDoc::VERSION # RDoc 1 does not have VERSION
68: 
69:     require 'rdoc/ri/driver'
70: 
71:     options = {
72:       :use_cache => true,
73:       :use_system => true,
74:       :use_site => true,
75:       :use_home => true,
76:       :use_gems => true,
77:       :formatter => RDoc::RI::Formatter,
78:     }
79: 
80:     driver = RDoc::RI::Driver.new(options).class_cache
81:   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 121
121:   def generate_rdoc
122:     setup_rdoc
123:     install_rdoc
124: 
125:     FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
126:   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 107
107:   def generate_ri
108:     setup_rdoc
109:     install_ri # RDoc bug, ri goes first
110: 
111:     FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
112:   end

Generate and install RDoc into the documentation directory

[Source]

     # File lib/rubygems/doc_manager.rb, line 131
131:   def install_rdoc
132:     rdoc_dir = File.join @doc_dir, 'rdoc'
133: 
134:     FileUtils.rm_rf rdoc_dir
135: 
136:     say "Installing RDoc documentation for #{@spec.full_name}..."
137:     run_rdoc '--op', rdoc_dir
138:   end

Generate and install RI into the documentation directory

[Source]

     # File lib/rubygems/doc_manager.rb, line 143
143:   def install_ri
144:     ri_dir = File.join @doc_dir, 'ri'
145: 
146:     FileUtils.rm_rf ri_dir
147: 
148:     say "Installing ri documentation for #{@spec.full_name}..."
149:     run_rdoc '--ri', '--op', ri_dir
150:   end

Is the RDoc documentation installed?

[Source]

    # File lib/rubygems/doc_manager.rb, line 96
96:   def rdoc_installed?
97:     File.exist?(File.join(@doc_dir, "rdoc"))
98:   end

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

[Source]

     # File lib/rubygems/doc_manager.rb, line 155
155:   def run_rdoc(*args)
156:     args << @spec.rdoc_options
157:     args << self.class.configured_args
158:     args << '--quiet'
159:     args << @spec.require_paths.clone
160:     args << @spec.extra_rdoc_files
161:     args << '--title' << "#{@spec.full_name} Documentation"
162:     args = args.flatten.map do |arg| arg.to_s end
163: 
164:     if self.class.rdoc_version >= Gem::Version.new('2.4.0') then
165:       args.delete '--inline-source'
166:       args.delete '--promiscuous'
167:       args.delete '-p'
168:       args.delete '--one-file'
169:       # HACK more
170:     end
171: 
172:     r = RDoc::RDoc.new
173: 
174:     old_pwd = Dir.pwd
175:     Dir.chdir(@spec.full_gem_path)
176:     begin
177:       r.document args
178:     rescue Errno::EACCES => e
179:       dirname = File.dirname e.message.split("-")[1].strip
180:       raise Gem::FilePermissionError.new(dirname)
181:     rescue RuntimeError => ex
182:       alert_error "While generating documentation for #{@spec.full_name}"
183:       ui.errs.puts "... MESSAGE:   #{ex}"
184:       ui.errs.puts "... RDOC args: #{args.join(' ')}"
185:       ui.errs.puts "\t#{ex.backtrace.join "\n\t"}" if
186:       Gem.configuration.backtrace
187:       ui.errs.puts "(continuing with the rest of the installation)"
188:     ensure
189:       Dir.chdir(old_pwd)
190:     end
191:   end

[Source]

     # File lib/rubygems/doc_manager.rb, line 193
193:   def setup_rdoc
194:     if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then
195:       raise Gem::FilePermissionError.new(@doc_dir)
196:     end
197: 
198:     FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
199: 
200:     self.class.load_rdoc
201:   end

Remove RDoc and RI documentation

[Source]

     # File lib/rubygems/doc_manager.rb, line 206
206:   def uninstall_doc
207:     raise Gem::FilePermissionError.new(@spec.installation_path) unless
208:     File.writable? @spec.installation_path
209: 
210:     original_name = [
211:       @spec.name, @spec.version, @spec.original_platform].join '-'
212: 
213:     doc_dir = File.join @spec.installation_path, 'doc', @spec.full_name
214:     unless File.directory? doc_dir then
215:       doc_dir = File.join @spec.installation_path, 'doc', original_name
216:     end
217: 
218:     FileUtils.rm_rf doc_dir
219: 
220:     ri_dir = File.join @spec.installation_path, 'ri', @spec.full_name
221: 
222:     unless File.directory? ri_dir then
223:       ri_dir = File.join @spec.installation_path, 'ri', original_name
224:     end
225: 
226:     FileUtils.rm_rf ri_dir
227:   end

[Validate]