class Gem::DocManager
The documentation manager generates RDoc and RI for RubyGems.
Public Class Methods
# File lib/rubygems/doc_manager.rb, line 18 def self.configured_args @configured_args ||= [] end
# File lib/rubygems/doc_manager.rb, line 22 def self.configured_args=(args) case args when Array @configured_args = args when String @configured_args = args.split end end
Load RDoc from a gem if it is available, otherwise from Ruby's stdlib
# File lib/rubygems/doc_manager.rb, line 34 def self.load_rdoc begin gem 'rdoc' rescue Gem::LoadError # use built-in RDoc end begin require 'rdoc/rdoc' @rdoc_version = if defined? RDoc::VERSION then Gem::Version.new RDoc::VERSION else Gem::Version.new '1.0.1' # HACK parsing is hard end rescue LoadError => e raise Gem::DocumentError, "ERROR: RDoc documentation generator not installed: #{e}" end 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 def initialize(spec, rdoc_args="") require 'fileutils' @spec = spec @doc_dir = spec.doc_dir @rdoc_args = rdoc_args.nil? ? [] : rdoc_args.split end
# File lib/rubygems/doc_manager.rb, line 56 def self.rdoc_version @rdoc_version end
Updates the RI cache for RDoc 2 if it is installed
# File lib/rubygems/doc_manager.rb, line 63 def self.update_ri_cache load_rdoc rescue return return unless defined? RDoc::VERSION # RDoc 1 does not have VERSION require 'rdoc/ri/driver' options = { :use_cache => true, :use_system => true, :use_site => true, :use_home => true, :use_gems => true, :formatter => RDoc::RI::Formatter, } RDoc::RI::Driver.new(options).class_cache end
Public Instance Methods
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 def generate_rdoc setup_rdoc install_rdoc FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) 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 def generate_ri setup_rdoc install_ri # RDoc bug, ri goes first FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) end
Generate and install RDoc into the documentation directory
# File lib/rubygems/doc_manager.rb, line 138 def install_rdoc rdoc_dir = File.join @doc_dir, 'rdoc' FileUtils.rm_rf rdoc_dir say "Installing RDoc documentation for #{@spec.full_name}..." run_rdoc '--op', rdoc_dir end
Generate and install RI into the documentation directory
# File lib/rubygems/doc_manager.rb, line 150 def install_ri ri_dir = File.join @doc_dir, 'ri' FileUtils.rm_rf ri_dir say "Installing ri documentation for #{@spec.full_name}..." run_rdoc '--ri', '--op', ri_dir end
Is the RDoc documentation installed?
# File lib/rubygems/doc_manager.rb, line 96 def rdoc_installed? File.exist?(File.join(@doc_dir, "rdoc")) end
Is the RI documentation installed?
# File lib/rubygems/doc_manager.rb, line 103 def ri_installed? File.exist?(File.join(@doc_dir, "ri")) end
Run RDoc with args
, which is an ARGV style argument list
# File lib/rubygems/doc_manager.rb, line 162 def run_rdoc(*args) args << @spec.rdoc_options args << self.class.configured_args args << @spec.require_paths.clone args << @spec.extra_rdoc_files args << '--title' << "#{@spec.full_name} Documentation" args << '--quiet' args = args.flatten.map do |arg| arg.to_s end if self.class.rdoc_version >= Gem::Version.new('2.4.0') then args.delete '--inline-source' args.delete '--promiscuous' args.delete '-p' args.delete '--one-file' # HACK more end debug_args = args.dup r = RDoc::RDoc.new old_pwd = Dir.pwd Dir.chdir @spec.full_gem_path say "rdoc #{args.join ' '}" if Gem.configuration.really_verbose begin r.document args rescue Errno::EACCES => e dirname = File.dirname e.message.split("-")[1].strip raise Gem::FilePermissionError.new(dirname) rescue Interrupt => e raise e rescue Exception => ex alert_error "While generating documentation for #{@spec.full_name}" ui.errs.puts "... MESSAGE: #{ex}" ui.errs.puts "... RDOC args: #{debug_args.join(' ')}" ui.errs.puts "\t#{ex.backtrace.join "\n\t"}" if Gem.configuration.backtrace terminate_interaction 1 ensure Dir.chdir old_pwd end end
# File lib/rubygems/doc_manager.rb, line 207 def setup_rdoc if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then raise Gem::FilePermissionError.new(@doc_dir) end FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) self.class.load_rdoc end
Remove RDoc and RI documentation
# File lib/rubygems/doc_manager.rb, line 220 def uninstall_doc base_dir = @spec.base_dir raise Gem::FilePermissionError.new base_dir unless File.writable? base_dir # TODO: ok... that's twice... ugh old_name = [ @spec.name, @spec.version, @spec.original_platform].join '-' doc_dir = @spec.doc_dir unless File.directory? doc_dir then doc_dir = File.join File.dirname(doc_dir), old_name end ri_dir = @spec.ri_dir unless File.directory? ri_dir then ri_dir = File.join File.dirname(ri_dir), old_name end FileUtils.rm_rf doc_dir FileUtils.rm_rf ri_dir end