Class | Gem::DocManager |
In: |
lib/rubygems/doc_manager.rb
|
Parent: | Object |
The documentation manager generates RDoc and RI for RubyGems.
# File lib/rubygems/doc_manager.rb, line 19 19: def self.configured_args 20: @configured_args ||= [] 21: end
# 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
# 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.
# 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
# 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
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 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).
# 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
# 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
# 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?
# 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
# 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
# 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
# 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