Parent

Included Modules

Class Index [+]

Quicksearch

Gem::DocManager

The documentation manager generates RDoc and RI for RubyGems.

Public Class Methods

configured_args() click to toggle source
    # File lib/rubygems/doc_manager.rb, line 19
19:   def self.configured_args
20:     @configured_args ||= []
21:   end
configured_args=(args) click to toggle 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() click to toggle source

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

    # 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
new(spec, rdoc_args="") click to toggle source

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

    # 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
rdoc_version() click to toggle source
    # File lib/rubygems/doc_manager.rb, line 57
57:   def self.rdoc_version
58:     @rdoc_version
59:   end
update_ri_cache() click to toggle source

Updates the RI cache for RDoc 2 if it is installed

    # 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_rdoc() click to toggle source

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).

     # File lib/rubygems/doc_manager.rb, line 128
128:   def generate_rdoc
129:     setup_rdoc
130:     install_rdoc
131: 
132:     FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
133:   end
generate_ri() click to toggle source

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).

     # File lib/rubygems/doc_manager.rb, line 114
114:   def generate_ri
115:     setup_rdoc
116:     install_ri # RDoc bug, ri goes first
117: 
118:     FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
119:   end
install_rdoc() click to toggle source

Generate and install RDoc into the documentation directory

     # File lib/rubygems/doc_manager.rb, line 138
138:   def install_rdoc
139:     rdoc_dir = File.join @doc_dir, 'rdoc'
140: 
141:     FileUtils.rm_rf rdoc_dir
142: 
143:     say "Installing RDoc documentation for #{@spec.full_name}..."
144:     run_rdoc '--op', rdoc_dir
145:   end
install_ri() click to toggle source

Generate and install RI into the documentation directory

     # File lib/rubygems/doc_manager.rb, line 150
150:   def install_ri
151:     ri_dir = File.join @doc_dir, 'ri'
152: 
153:     FileUtils.rm_rf ri_dir
154: 
155:     say "Installing ri documentation for #{@spec.full_name}..."
156:     run_rdoc '--ri', '--op', ri_dir
157:   end
rdoc_installed?() click to toggle source

Is the RDoc documentation installed?

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

Is the RI documentation installed?

     # File lib/rubygems/doc_manager.rb, line 103
103:   def ri_installed?
104:     File.exist?(File.join(@doc_dir, "ri"))
105:   end
run_rdoc(*args) click to toggle source

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

     # File lib/rubygems/doc_manager.rb, line 162
162:   def run_rdoc(*args)
163:     args << @spec.rdoc_options
164:     args << self.class.configured_args
165:     args << '--quiet'
166:     args << @spec.require_paths.clone
167:     args << @spec.extra_rdoc_files
168:     args << '--title' << "#{@spec.full_name} Documentation"
169:     args = args.flatten.map do |arg| arg.to_s end
170: 
171:     if self.class.rdoc_version >= Gem::Version.new('2.4.0') then
172:       args.delete '--inline-source'
173:       args.delete '--promiscuous'
174:       args.delete '-p'
175:       args.delete '--one-file'
176:       # HACK more
177:     end
178: 
179:     r = RDoc::RDoc.new
180: 
181:     old_pwd = Dir.pwd
182:     Dir.chdir @spec.full_gem_path
183: 
184:     say "rdoc #{args.join ' '}" if Gem.configuration.really_verbose
185: 
186:     begin
187:       r.document args
188:     rescue Errno::EACCES => e
189:       dirname = File.dirname e.message.split("-")[1].strip
190:       raise Gem::FilePermissionError.new(dirname)
191:     rescue RuntimeError => ex
192:       alert_error "While generating documentation for #{@spec.full_name}"
193:       ui.errs.puts "... MESSAGE:   #{ex}"
194:       ui.errs.puts "... RDOC args: #{args.join(' ')}"
195:       ui.errs.puts "\t#{ex.backtrace.join "\n\t"}" if
196:       Gem.configuration.backtrace
197:       ui.errs.puts "(continuing with the rest of the installation)"
198:     ensure
199:       Dir.chdir old_pwd
200:     end
201:   end
setup_rdoc() click to toggle source
     # File lib/rubygems/doc_manager.rb, line 203
203:   def setup_rdoc
204:     if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then
205:       raise Gem::FilePermissionError.new(@doc_dir)
206:     end
207: 
208:     FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
209: 
210:     self.class.load_rdoc
211:   end
uninstall_doc() click to toggle source

Remove RDoc and RI documentation

     # File lib/rubygems/doc_manager.rb, line 216
216:   def uninstall_doc
217:     raise Gem::FilePermissionError.new(@spec.installation_path) unless
218:     File.writable? @spec.installation_path
219: 
220:     original_name = [
221:       @spec.name, @spec.version, @spec.original_platform].join '-'
222: 
223:     doc_dir = File.join @spec.installation_path, 'doc', @spec.full_name
224:     unless File.directory? doc_dir then
225:       doc_dir = File.join @spec.installation_path, 'doc', original_name
226:     end
227: 
228:     FileUtils.rm_rf doc_dir
229: 
230:     ri_dir = File.join @spec.installation_path, 'ri', @spec.full_name
231: 
232:     unless File.directory? ri_dir then
233:       ri_dir = File.join @spec.installation_path, 'ri', original_name
234:     end
235: 
236:     FileUtils.rm_rf ri_dir
237:   end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.