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 121 121: def generate_rdoc 122: setup_rdoc 123: install_rdoc 124: 125: FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) 126: 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 107 107: def generate_ri 108: setup_rdoc 109: install_ri # RDoc bug, ri goes first 110: 111: FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) 112: end
Generate and install RDoc into the documentation directory
# File lib/rubygems/doc_manager.rb, line 131 131: def install_rdoc 132: rdoc_dir = File.join @doc_dir, 'rdoc' 133: 134: FileUtils.rm_rf rdoc_dir 135: 136: say "Installing RDoc documentation for #{@spec.full_name}..." 137: run_rdoc '--op', rdoc_dir 138: end
Generate and install RI into the documentation directory
# File lib/rubygems/doc_manager.rb, line 143 143: def install_ri 144: ri_dir = File.join @doc_dir, 'ri' 145: 146: FileUtils.rm_rf ri_dir 147: 148: say "Installing ri documentation for #{@spec.full_name}..." 149: run_rdoc '--ri', '--op', ri_dir 150: 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
Run RDoc with args, which is an ARGV style argument list
# File lib/rubygems/doc_manager.rb, line 155 155: def run_rdoc(*args) 156: args << @spec.rdoc_options 157: args << self.class.configured_args 158: args << '--quiet' 159: args << @spec.require_paths.clone 160: args << @spec.extra_rdoc_files 161: args << '--title' << "#{@spec.full_name} Documentation" 162: args = args.flatten.map do |arg| arg.to_s end 163: 164: if self.class.rdoc_version >= Gem::Version.new('2.4.0') then 165: args.delete '--inline-source' 166: args.delete '--promiscuous' 167: args.delete '-p' 168: args.delete '--one-file' 169: # HACK more 170: end 171: 172: r = RDoc::RDoc.new 173: 174: old_pwd = Dir.pwd 175: Dir.chdir(@spec.full_gem_path) 176: begin 177: r.document args 178: rescue Errno::EACCES => e 179: dirname = File.dirname e.message.split("-")[1].strip 180: raise Gem::FilePermissionError.new(dirname) 181: rescue RuntimeError => ex 182: alert_error "While generating documentation for #{@spec.full_name}" 183: ui.errs.puts "... MESSAGE: #{ex}" 184: ui.errs.puts "... RDOC args: #{args.join(' ')}" 185: ui.errs.puts "\t#{ex.backtrace.join "\n\t"}" if 186: Gem.configuration.backtrace 187: ui.errs.puts "(continuing with the rest of the installation)" 188: ensure 189: Dir.chdir(old_pwd) 190: end 191: end
# File lib/rubygems/doc_manager.rb, line 193 193: def setup_rdoc 194: if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then 195: raise Gem::FilePermissionError.new(@doc_dir) 196: end 197: 198: FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) 199: 200: self.class.load_rdoc 201: end
Remove RDoc and RI documentation
# File lib/rubygems/doc_manager.rb, line 206 206: def uninstall_doc 207: raise Gem::FilePermissionError.new(@spec.installation_path) unless 208: File.writable? @spec.installation_path 209: 210: original_name = [ 211: @spec.name, @spec.version, @spec.original_platform].join '-' 212: 213: doc_dir = File.join @spec.installation_path, 'doc', @spec.full_name 214: unless File.directory? doc_dir then 215: doc_dir = File.join @spec.installation_path, 'doc', original_name 216: end 217: 218: FileUtils.rm_rf doc_dir 219: 220: ri_dir = File.join @spec.installation_path, 'ri', @spec.full_name 221: 222: unless File.directory? ri_dir then 223: ri_dir = File.join @spec.installation_path, 'ri', original_name 224: end 225: 226: FileUtils.rm_rf ri_dir 227: end