diff options
Diffstat (limited to 'ruby_1_9_3/lib/rubygems/doc_manager.rb')
| -rw-r--r-- | ruby_1_9_3/lib/rubygems/doc_manager.rb | 243 |
1 files changed, 243 insertions, 0 deletions
diff --git a/ruby_1_9_3/lib/rubygems/doc_manager.rb b/ruby_1_9_3/lib/rubygems/doc_manager.rb new file mode 100644 index 0000000000..826f57d9dd --- /dev/null +++ b/ruby_1_9_3/lib/rubygems/doc_manager.rb @@ -0,0 +1,243 @@ +#-- +# Copyright 2006 by Chad Fowler, Rich Kilmer, Jim Weirich and others. +# All rights reserved. +# See LICENSE.txt for permissions. +#++ + +require 'rubygems' + +## +# The documentation manager generates RDoc and RI for RubyGems. + +class Gem::DocManager + + include Gem::UserInteraction + + @configured_args = [] + + def self.configured_args + @configured_args ||= [] + end + + 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 + + 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 + + def self.rdoc_version + @rdoc_version + end + + ## + # Updates the RI cache for RDoc 2 if it is installed + + 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 + + ## + # Create a document manager for +spec+. +rdoc_args+ contains arguments for + # RDoc (template etc.) as a String. + + def initialize(spec, rdoc_args="") + require 'fileutils' + @spec = spec + @doc_dir = spec.doc_dir + @rdoc_args = rdoc_args.nil? ? [] : rdoc_args.split + end + + ## + # Is the RDoc documentation installed? + + def rdoc_installed? + File.exist?(File.join(@doc_dir, "rdoc")) + end + + ## + # Is the RI documentation installed? + + def ri_installed? + File.exist?(File.join(@doc_dir, "ri")) + 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). + + def generate_ri + setup_rdoc + install_ri # RDoc bug, ri goes first + + FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) + 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). + + def generate_rdoc + setup_rdoc + install_rdoc + + FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) + end + + ## + # Generate and install RDoc into the documentation directory + + 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 + + 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 + + ## + # Run RDoc with +args+, which is an ARGV style argument list + + 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 + + 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 + + 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 + +end + |