lib/rubygems/doc_manager.rb

   1 #--
   2 # Copyright 2006 by Chad Fowler, Rich Kilmer, Jim Weirich and others.
   3 # All rights reserved.
   4 # See LICENSE.txt for permissions.
   5 #++
   6
   7 require 'fileutils'
   8
   9 module Gem
  10
  11   class DocManager
  12
  13     include UserInteraction
  14
  15     # Create a document manager for the given gem spec.
  16     #
  17     # spec::      The Gem::Specification object representing the gem.
  18     # rdoc_args:: Optional arguments for RDoc (template etc.) as a String.
  19     #
  20     def initialize(spec, rdoc_args="")
  21       @spec = spec
  22       @doc_dir = File.join(spec.installation_path, "doc", spec.full_name)
  23       @rdoc_args = rdoc_args.nil? ? [] : rdoc_args.split
  24     end
  25
  26     # Is the RDoc documentation installed?
  27     def rdoc_installed?
  28       return File.exist?(File.join(@doc_dir, "rdoc"))
  29     end
  30
  31     # Generate the RI documents for this gem spec.
  32     #
  33     # Note that if both RI and RDoc documents are generated from the
  34     # same process, the RI docs should be done first (a likely bug in
  35     # RDoc will cause RI docs generation to fail if run after RDoc).
  36     def generate_ri
  37       if @spec.has_rdoc then
  38         load_rdoc
  39         install_ri # RDoc bug, ri goes first
  40       end
  41
  42       FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
  43     end
  44
  45     # Generate the RDoc documents for this gem spec.
  46     #
  47     # Note that if both RI and RDoc documents are generated from the
  48     # same process, the RI docs should be done first (a likely bug in
  49     # RDoc will cause RI docs generation to fail if run after RDoc).
  50     def generate_rdoc
  51       if @spec.has_rdoc then
  52         load_rdoc
  53         install_rdoc
  54       end
  55
  56       FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
  57     end
  58
  59     # Load the RDoc documentation generator library.
  60     def load_rdoc
  61       if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then
  62         raise Gem::FilePermissionError.new(@doc_dir)
  63       end
  64
  65       FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
  66
  67       begin
  68         gem 'rdoc'
  69       rescue Gem::LoadError
  70         # use built-in RDoc
  71       end
  72
  73       begin
  74         require 'rdoc/rdoc'
  75       rescue LoadError => e
  76         raise Gem::DocumentError,
  77           "ERROR: RDoc documentation generator not installed!"
  78       end
  79     end
  80
  81     def install_rdoc
  82       rdoc_dir = File.join @doc_dir, 'rdoc'
  83
  84       FileUtils.rm_rf rdoc_dir
  85
  86       say "Installing RDoc documentation for #{@spec.full_name}..."
  87       run_rdoc '--op', rdoc_dir
  88     end
  89
  90     def install_ri
  91       ri_dir = File.join @doc_dir, 'ri'
  92
  93       FileUtils.rm_rf ri_dir
  94
  95       say "Installing ri documentation for #{@spec.full_name}..."
  96       run_rdoc '--ri', '--op', ri_dir
  97     end
  98
  99     def run_rdoc(*args)
 100       args << @spec.rdoc_options
 101       args << DocManager.configured_args
 102       args << '--quiet'
 103       args << @spec.require_paths.clone
 104       args << @spec.extra_rdoc_files
 105       args = args.flatten.map do |arg| arg.to_s end
 106
 107       r = RDoc::RDoc.new
 108
 109       old_pwd = Dir.pwd
 110       Dir.chdir(@spec.full_gem_path)
 111       begin
 112         r.document args
 113       rescue Errno::EACCES => e
 114         dirname = File.dirname e.message.split("-")[1].strip
 115         raise Gem::FilePermissionError.new(dirname)
 116       rescue RuntimeError => ex
 117         alert_error "While generating documentation for #{@spec.full_name}"
 118         ui.errs.puts "... MESSAGE:   #{ex}"
 119         ui.errs.puts "... RDOC args: #{args.join(' ')}"
 120         ui.errs.puts "\t#{ex.backtrace.join "\n\t"}" if
 121           Gem.configuration.backtrace
 122         ui.errs.puts "(continuing with the rest of the installation)"
 123       ensure
 124         Dir.chdir(old_pwd)
 125       end
 126     end
 127
 128     def uninstall_doc
 129       raise Gem::FilePermissionError.new(@spec.installation_path) unless
 130         File.writable? @spec.installation_path
 131
 132       original_name = [
 133         @spec.name, @spec.version, @spec.original_platform].join '-'
 134
 135       doc_dir = File.join @spec.installation_path, 'doc', @spec.full_name
 136       unless File.directory? doc_dir then
 137         doc_dir = File.join @spec.installation_path, 'doc', original_name
 138       end
 139
 140       FileUtils.rm_rf doc_dir
 141
 142       ri_dir = File.join @spec.installation_path, 'ri', @spec.full_name
 143
 144       unless File.directory? ri_dir then
 145         ri_dir = File.join @spec.installation_path, 'ri', original_name
 146       end
 147
 148       FileUtils.rm_rf ri_dir
 149     end
 150
 151     class << self
 152       def configured_args
 153         @configured_args ||= []
 154       end
 155
 156       def configured_args=(args)
 157         case args
 158         when Array
 159           @configured_args = args
 160         when String
 161           @configured_args = args.split
 162         end
 163       end
 164     end
 165
 166   end
 167 end