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: 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.
# 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
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
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 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
# 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
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