PageRenderTime 131ms CodeModel.GetById 111ms app.highlight 17ms RepoModel.GetById 1ms app.codeStats 0ms

/tools/Ruby/lib/ruby/site_ruby/1.8/rubygems/doc_manager.rb

http://github.com/agross/netopenspace
Ruby | 244 lines | 144 code | 60 blank | 40 comment | 7 complexity | 8edbe10894581461dda7ba50cece4f9a MD5 | raw file
  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
  7require 'rubygems'
  8
  9##
 10# The documentation manager generates RDoc and RI for RubyGems.
 11
 12class Gem::DocManager
 13
 14  include Gem::UserInteraction
 15
 16  @configured_args = []
 17
 18  def self.configured_args
 19    @configured_args ||= []
 20  end
 21
 22  def self.configured_args=(args)
 23    case args
 24    when Array
 25      @configured_args = args
 26    when String
 27      @configured_args = args.split
 28    end
 29  end
 30
 31  ##
 32  # Load RDoc from a gem if it is available, otherwise from Ruby's stdlib
 33
 34  def self.load_rdoc
 35    begin
 36      gem 'rdoc'
 37    rescue Gem::LoadError
 38      # use built-in RDoc
 39    end
 40
 41    begin
 42      require 'rdoc/rdoc'
 43
 44      @rdoc_version = if defined? RDoc::VERSION then
 45                        Gem::Version.new RDoc::VERSION
 46                      else
 47                        Gem::Version.new '1.0.1' # HACK parsing is hard
 48                      end
 49
 50    rescue LoadError => e
 51      raise Gem::DocumentError,
 52          "ERROR: RDoc documentation generator not installed: #{e}"
 53    end
 54  end
 55
 56  def self.rdoc_version
 57    @rdoc_version
 58  end
 59
 60  ##
 61  # Updates the RI cache for RDoc 2 if it is installed
 62
 63  def self.update_ri_cache
 64    load_rdoc rescue return
 65
 66    return unless defined? RDoc::VERSION # RDoc 1 does not have VERSION
 67
 68    require 'rdoc/ri/driver'
 69
 70    options = {
 71      :use_cache => true,
 72      :use_system => true,
 73      :use_site => true,
 74      :use_home => true,
 75      :use_gems => true,
 76      :formatter => RDoc::RI::Formatter,
 77    }
 78
 79    RDoc::RI::Driver.new(options).class_cache
 80  end
 81
 82  ##
 83  # Create a document manager for +spec+. +rdoc_args+ contains arguments for
 84  # RDoc (template etc.) as a String.
 85
 86  def initialize(spec, rdoc_args="")
 87    require 'fileutils'
 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
 92
 93  ##
 94  # Is the RDoc documentation installed?
 95
 96  def rdoc_installed?
 97    File.exist?(File.join(@doc_dir, "rdoc"))
 98  end
 99
100  ##
101  # Is the RI documentation installed?
102
103  def ri_installed?
104    File.exist?(File.join(@doc_dir, "ri"))
105  end
106
107  ##
108  # Generate the RI documents for this gem spec.
109  #
110  # Note that if both RI and RDoc documents are generated from the same
111  # process, the RI docs should be done first (a likely bug in RDoc will cause
112  # RI docs generation to fail if run after RDoc).
113
114  def generate_ri
115    setup_rdoc
116    install_ri # RDoc bug, ri goes first
117
118    FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
119  end
120
121  ##
122  # Generate the RDoc documents for this gem spec.
123  #
124  # Note that if both RI and RDoc documents are generated from the same
125  # process, the RI docs should be done first (a likely bug in RDoc will cause
126  # RI docs generation to fail if run after RDoc).
127
128  def generate_rdoc
129    setup_rdoc
130    install_rdoc
131
132    FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
133  end
134
135  ##
136  # Generate and install RDoc into the documentation directory
137
138  def install_rdoc
139    rdoc_dir = File.join @doc_dir, 'rdoc'
140
141    FileUtils.rm_rf rdoc_dir
142
143    say "Installing RDoc documentation for #{@spec.full_name}..."
144    run_rdoc '--op', rdoc_dir
145  end
146
147  ##
148  # Generate and install RI into the documentation directory
149
150  def install_ri
151    ri_dir = File.join @doc_dir, 'ri'
152
153    FileUtils.rm_rf ri_dir
154
155    say "Installing ri documentation for #{@spec.full_name}..."
156    run_rdoc '--ri', '--op', ri_dir
157  end
158
159  ##
160  # Run RDoc with +args+, which is an ARGV style argument list
161
162  def run_rdoc(*args)
163    args << @spec.rdoc_options
164    args << self.class.configured_args
165    args << @spec.require_paths.clone
166    args << @spec.extra_rdoc_files
167    args << '--title' << "#{@spec.full_name} Documentation"
168    args << '--quiet'
169    args = args.flatten.map do |arg| arg.to_s end
170
171    if self.class.rdoc_version >= Gem::Version.new('2.4.0') then
172      args.delete '--inline-source'
173      args.delete '--promiscuous'
174      args.delete '-p'
175      args.delete '--one-file'
176      # HACK more
177    end
178
179    debug_args = args.dup
180
181    r = RDoc::RDoc.new
182
183    old_pwd = Dir.pwd
184    Dir.chdir @spec.full_gem_path
185
186    say "rdoc #{args.join ' '}" if Gem.configuration.really_verbose
187
188    begin
189      r.document args
190    rescue Errno::EACCES => e
191      dirname = File.dirname e.message.split("-")[1].strip
192      raise Gem::FilePermissionError.new(dirname)
193    rescue Interrupt => e
194      raise e
195    rescue Exception => ex
196      alert_error "While generating documentation for #{@spec.full_name}"
197      ui.errs.puts "... MESSAGE:   #{ex}"
198      ui.errs.puts "... RDOC args: #{debug_args.join(' ')}"
199      ui.errs.puts "\t#{ex.backtrace.join "\n\t"}" if
200        Gem.configuration.backtrace
201      terminate_interaction 1
202    ensure
203      Dir.chdir old_pwd
204    end
205  end
206
207  def setup_rdoc
208    if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then
209      raise Gem::FilePermissionError.new(@doc_dir)
210    end
211
212    FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
213
214    self.class.load_rdoc
215  end
216
217  ##
218  # Remove RDoc and RI documentation
219
220  def uninstall_doc
221    raise Gem::FilePermissionError.new(@spec.installation_path) unless
222    File.writable? @spec.installation_path
223
224    original_name = [
225      @spec.name, @spec.version, @spec.original_platform].join '-'
226
227    doc_dir = File.join @spec.installation_path, 'doc', @spec.full_name
228    unless File.directory? doc_dir then
229      doc_dir = File.join @spec.installation_path, 'doc', original_name
230    end
231
232    FileUtils.rm_rf doc_dir
233
234    ri_dir = File.join @spec.installation_path, 'ri', @spec.full_name
235
236    unless File.directory? ri_dir then
237      ri_dir = File.join @spec.installation_path, 'ri', original_name
238    end
239
240    FileUtils.rm_rf ri_dir
241  end
242
243end
244