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 << @spec.require_paths.clone 166: args << @spec.extra_rdoc_files 167: args << '--title' << "#{@spec.full_name} Documentation" 168: args << '--quiet' 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: debug_args = args.dup 180: 181: r = RDoc::RDoc.new 182: 183: old_pwd = Dir.pwd 184: Dir.chdir @spec.full_gem_path 185: 186: say "rdoc #{args.join ' '}" if Gem.configuration.really_verbose 187: 188: begin 189: r.document args 190: rescue Errno::EACCES => e 191: dirname = File.dirname e.message.split("-")[1].strip 192: raise Gem::FilePermissionError.new(dirname) 193: rescue Interrupt => e 194: raise e 195: rescue Exception => ex 196: alert_error "While generating documentation for #{@spec.full_name}" 197: ui.errs.puts "... MESSAGE: #{ex}" 198: ui.errs.puts "... RDOC args: #{debug_args.join(' ')}" 199: ui.errs.puts "\t#{ex.backtrace.join "\n\t"}" if 200: Gem.configuration.backtrace 201: terminate_interaction 1 202: ensure 203: Dir.chdir old_pwd 204: end 205: end
# File lib/rubygems/doc_manager.rb, line 207 207: def setup_rdoc 208: if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then 209: raise Gem::FilePermissionError.new(@doc_dir) 210: end 211: 212: FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) 213: 214: self.class.load_rdoc 215: end
Remove RDoc and RI documentation
# File lib/rubygems/doc_manager.rb, line 220 220: def uninstall_doc 221: raise Gem::FilePermissionError.new(@spec.installation_path) unless 222: File.writable? @spec.installation_path 223: 224: original_name = [ 225: @spec.name, @spec.version, @spec.original_platform].join '-' 226: 227: doc_dir = File.join @spec.installation_path, 'doc', @spec.full_name 228: unless File.directory? doc_dir then 229: doc_dir = File.join @spec.installation_path, 'doc', original_name 230: end 231: 232: FileUtils.rm_rf doc_dir 233: 234: ri_dir = File.join @spec.installation_path, 'ri', @spec.full_name 235: 236: unless File.directory? ri_dir then 237: ri_dir = File.join @spec.installation_path, 'ri', original_name 238: end 239: 240: FileUtils.rm_rf ri_dir 241: end