diff options
Diffstat (limited to 'lib/rubygems/doc_manager.rb')
| -rw-r--r-- | lib/rubygems/doc_manager.rb | 277 |
1 files changed, 162 insertions, 115 deletions
diff --git a/lib/rubygems/doc_manager.rb b/lib/rubygems/doc_manager.rb index 88d7964d85..00ef4c51e3 100644 --- a/lib/rubygems/doc_manager.rb +++ b/lib/rubygems/doc_manager.rb @@ -5,132 +5,194 @@ #++ require 'fileutils' +require 'rubygems' -module Gem +## +# The documentation manager generates RDoc and RI for RubyGems. - class DocManager +class Gem::DocManager - include UserInteraction + include Gem::UserInteraction - # Create a document manager for the given gem spec. - # - # spec:: The Gem::Specification object representing the gem. - # rdoc_args:: Optional arguments for RDoc (template etc.) as a String. - # - def initialize(spec, rdoc_args="") - @spec = spec - @doc_dir = File.join(spec.installation_path, "doc", spec.full_name) - @rdoc_args = rdoc_args.nil? ? [] : rdoc_args.split + @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 - # Is the RDoc documentation installed? - def rdoc_installed? - return File.exist?(File.join(@doc_dir, "rdoc")) + def self.load_rdoc + begin + gem 'rdoc' + rescue Gem::LoadError + # use built-in RDoc 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 - if @spec.has_rdoc then - load_rdoc - install_ri # RDoc bug, ri goes first - end + begin + require 'rdoc/rdoc' + rescue LoadError => e + raise Gem::DocumentError, + "ERROR: RDoc documentation generator not installed!" + end + 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 - FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) + require 'rdoc/ri/driver' + + options = { + :use_cache => true, + :use_system => true, + :use_site => true, + :use_home => true, + :use_gems => true, + :formatter => RDoc::RI::Formatter, + } + + driver = 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="") + @spec = spec + @doc_dir = File.join(spec.installation_path, "doc", spec.full_name) + @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 + + ## + # 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 + if @spec.has_rdoc then + setup_rdoc + install_ri # RDoc bug, ri goes first 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 - if @spec.has_rdoc then - load_rdoc - install_rdoc - end + FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) + end - FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) + ## + # 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 + if @spec.has_rdoc then + setup_rdoc + install_rdoc end - # Load the RDoc documentation generator library. - def load_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) + end - FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) + ## + # Generate and install RDoc into the documentation directory - begin - gem 'rdoc' - rescue Gem::LoadError - # use built-in RDoc - end + def install_rdoc + rdoc_dir = File.join @doc_dir, 'rdoc' - begin - require 'rdoc/rdoc' - rescue LoadError => e - raise Gem::DocumentError, - "ERROR: RDoc documentation generator not installed!" - end - end + FileUtils.rm_rf rdoc_dir - def install_rdoc - rdoc_dir = File.join @doc_dir, 'rdoc' + say "Installing RDoc documentation for #{@spec.full_name}..." + run_rdoc '--op', rdoc_dir + end - FileUtils.rm_rf rdoc_dir + ## + # Generate and install RI into the documentation directory - say "Installing RDoc documentation for #{@spec.full_name}..." - run_rdoc '--op', rdoc_dir - end + def install_ri + ri_dir = File.join @doc_dir, 'ri' - def install_ri - ri_dir = File.join @doc_dir, 'ri' + FileUtils.rm_rf ri_dir - FileUtils.rm_rf ri_dir + say "Installing ri documentation for #{@spec.full_name}..." + run_rdoc '--ri', '--op', ri_dir + end - say "Installing ri documentation for #{@spec.full_name}..." - run_rdoc '--ri', '--op', ri_dir + ## + # 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 << '--quiet' + args << @spec.require_paths.clone + args << @spec.extra_rdoc_files + args = args.flatten.map do |arg| arg.to_s end + + r = RDoc::RDoc.new + + old_pwd = Dir.pwd + Dir.chdir(@spec.full_gem_path) + begin + r.document args + rescue Errno::EACCES => e + dirname = File.dirname e.message.split("-")[1].strip + raise Gem::FilePermissionError.new(dirname) + rescue RuntimeError => ex + alert_error "While generating documentation for #{@spec.full_name}" + ui.errs.puts "... MESSAGE: #{ex}" + ui.errs.puts "... RDOC args: #{args.join(' ')}" + ui.errs.puts "\t#{ex.backtrace.join "\n\t"}" if + Gem.configuration.backtrace + ui.errs.puts "(continuing with the rest of the installation)" + ensure + Dir.chdir(old_pwd) end + end - def run_rdoc(*args) - args << @spec.rdoc_options - args << DocManager.configured_args - args << '--quiet' - args << @spec.require_paths.clone - args << @spec.extra_rdoc_files - args = args.flatten.map do |arg| arg.to_s end - - r = RDoc::RDoc.new - - old_pwd = Dir.pwd - Dir.chdir(@spec.full_gem_path) - begin - r.document args - rescue Errno::EACCES => e - dirname = File.dirname e.message.split("-")[1].strip - raise Gem::FilePermissionError.new(dirname) - rescue RuntimeError => ex - alert_error "While generating documentation for #{@spec.full_name}" - ui.errs.puts "... MESSAGE: #{ex}" - ui.errs.puts "... RDOC args: #{args.join(' ')}" - ui.errs.puts "\t#{ex.backtrace.join "\n\t"}" if - Gem.configuration.backtrace - ui.errs.puts "(continuing with the rest of the installation)" - ensure - Dir.chdir(old_pwd) - end + def setup_rdoc + if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then + raise Gem::FilePermissionError.new(@doc_dir) end - def uninstall_doc - raise Gem::FilePermissionError.new(@spec.installation_path) unless - File.writable? @spec.installation_path + FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) - original_name = [ - @spec.name, @spec.version, @spec.original_platform].join '-' + self.class.load_rdoc + end + + ## + # Remove RDoc and RI documentation + + def uninstall_doc + raise Gem::FilePermissionError.new(@spec.installation_path) unless + File.writable? @spec.installation_path + + original_name = [ + @spec.name, @spec.version, @spec.original_platform].join '-' doc_dir = File.join @spec.installation_path, 'doc', @spec.full_name unless File.directory? doc_dir then @@ -146,22 +208,7 @@ module Gem end FileUtils.rm_rf ri_dir - end - - class << self - def configured_args - @configured_args ||= [] - end - - def configured_args=(args) - case args - when Array - @configured_args = args - when String - @configured_args = args.split - end - end - end - end + end + |