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 18 18: def self.configured_args 19: @configured_args ||= [] 20: end
# File lib/rubygems/doc_manager.rb, line 22 22: def self.configured_args=(args) 23: case args 24: when Array 25: @configured_args = args 26: when String 27: @configured_args = args.split 28: end 29: end
Load RDoc from a gem if it is available, otherwise from Ruby‘s stdlib
# File lib/rubygems/doc_manager.rb, line 34 34: def self.load_rdoc 35: begin 36: gem 'rdoc' 37: rescue Gem::LoadError 38: # use built-in RDoc 39: end 40: 41: begin 42: require 'rdoc/rdoc' 43: 44: @rdoc_version = if defined? RDoc::VERSION then 45: Gem::Version.new RDoc::VERSION 46: else 47: Gem::Version.new '1.0.1' # HACK parsing is hard 48: end 49: 50: rescue LoadError => e 51: raise Gem::DocumentError, 52: "ERROR: RDoc documentation generator not installed: #{e}" 53: end 54: 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 86 86: def initialize(spec, rdoc_args="") 87: require 'fileutils' 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
Updates the RI cache for RDoc 2 if it is installed
# File lib/rubygems/doc_manager.rb, line 63 63: def self.update_ri_cache 64: load_rdoc rescue return 65: 66: return unless defined? RDoc::VERSION # RDoc 1 does not have VERSION 67: 68: require 'rdoc/ri/driver' 69: 70: options = { 71: :use_cache => true, 72: :use_system => true, 73: :use_site => true, 74: :use_home => true, 75: :use_gems => true, 76: :formatter => RDoc::RI::Formatter, 77: } 78: 79: RDoc::RI::Driver.new(options).class_cache 80: 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 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 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
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
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
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
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 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 Interrupt => e 192: raise e 193: rescue Exception => ex 194: alert_error "While generating documentation for #{@spec.full_name}" 195: ui.errs.puts "... MESSAGE: #{ex}" 196: ui.errs.puts "... RDOC args: #{args.join(' ')}" 197: ui.errs.puts "\t#{ex.backtrace.join "\n\t"}" if 198: Gem.configuration.backtrace 199: ui.errs.puts "(continuing with the rest of the installation)" 200: ensure 201: Dir.chdir old_pwd 202: end 203: end
# File lib/rubygems/doc_manager.rb, line 205 205: def setup_rdoc 206: if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then 207: raise Gem::FilePermissionError.new(@doc_dir) 208: end 209: 210: FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) 211: 212: self.class.load_rdoc 213: end
Remove RDoc and RI documentation
# File lib/rubygems/doc_manager.rb, line 218 218: def uninstall_doc 219: raise Gem::FilePermissionError.new(@spec.installation_path) unless 220: File.writable? @spec.installation_path 221: 222: original_name = [ 223: @spec.name, @spec.version, @spec.original_platform].join '-' 224: 225: doc_dir = File.join @spec.installation_path, 'doc', @spec.full_name 226: unless File.directory? doc_dir then 227: doc_dir = File.join @spec.installation_path, 'doc', original_name 228: end 229: 230: FileUtils.rm_rf doc_dir 231: 232: ri_dir = File.join @spec.installation_path, 'ri', @spec.full_name 233: 234: unless File.directory? ri_dir then 235: ri_dir = File.join @spec.installation_path, 'ri', original_name 236: end 237: 238: FileUtils.rm_rf ri_dir 239: end