Extended maintenance of Ruby 1.9.3 ended on February 23, 2015. Read more
The documentation manager generates RDoc and RI for RubyGems.
# File rubygems/doc_manager.rb, line 18 def self.configured_args @configured_args ||= [] end
# File 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 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 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 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 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
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 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 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 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 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 rubygems/doc_manager.rb, line 96 def rdoc_installed? File.exist?(File.join(@doc_dir, "rdoc")) end
Is the RI documentation installed?
# File 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 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 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 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
Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.
If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.
If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.
If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.