Class: Gem::DocManager

Inherits:
Object
  • Object
show all
Includes:
UserInteraction
Defined in:
lib/rubygems/doc_manager.rb

Class Method Summary collapse

Instance Method Summary collapse

Methods included from DefaultUserInteraction

#ui, ui, #ui=, ui=, #use_ui, use_ui

Constructor Details

#initialize(spec, rdoc_args = "") ⇒ DocManager

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.



20
21
22
23
24
25
 
# File 'lib/rubygems/doc_manager.rb', line 20

def initialize(spec, rdoc_args="")
  @spec = spec
  @doc_dir = File.join(spec.installation_path, "doc", spec.full_name)
  Gem::FilePermissionError.new(spec.installation_path) unless File.writable?(spec.installation_path)
  @rdoc_args = rdoc_args.nil? ? [] : rdoc_args.split
end

Class Method Details

.configured_args ⇒ Object 



124
125
126
 
# File 'lib/rubygems/doc_manager.rb', line 124

def configured_args
  @configured_args ||= []
end

.configured_args=(args) ⇒ Object 



128
129
130
131
132
133
134
135
 
# File 'lib/rubygems/doc_manager.rb', line 128

def configured_args=(args)
  case args
  when Array
    @configured_args = args
  when String
    @configured_args = args.split
  end
end

Instance Method Details

#generate_rdoc ⇒ Object

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).



53
54
55
56
57
58
59
60
61
62
 
# File 'lib/rubygems/doc_manager.rb', line 53

def generate_rdoc
  require 'fileutils'

  if @spec.has_rdoc then
    load_rdoc
    install_rdoc
  end

  FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
end

#generate_ri ⇒ Object

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).



37
38
39
40
41
42
43
44
45
46
 
# File 'lib/rubygems/doc_manager.rb', line 37

def generate_ri
  require 'fileutils'

  if @spec.has_rdoc then
    load_rdoc
    install_ri # RDoc bug, ri goes first
  end

  FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
end

#install_rdoc ⇒ Object 



78
79
80
81
 
# File 'lib/rubygems/doc_manager.rb', line 78

def install_rdoc
  say "Installing RDoc documentation for #{@spec.full_name}..."
  run_rdoc '--op', File.join(@doc_dir, 'rdoc')
end

#install_ri ⇒ Object 



83
84
85
86
 
# File 'lib/rubygems/doc_manager.rb', line 83

def install_ri
  say "Installing ri documentation for #{@spec.full_name}..."
  run_rdoc '--ri', '--op', File.join(@doc_dir, 'ri')
end

#load_rdoc ⇒ Object

Load the RDoc documentation generator library.



65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/rubygems/doc_manager.rb', line 65

def load_rdoc
  if File.exist?(@doc_dir) && !File.writable?(@doc_dir)
    Gem::FilePermissionError.new(@doc_dir)
  end
  FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
  begin
    require 'rdoc/rdoc'
  rescue LoadError => e
    raise DocumentError, 
      "ERROR: RDoc documentation generator not installed!"
  end
end

#rdoc_installed? ⇒ Boolean

Is the RDoc documentation installed?

Returns:

  • (Boolean) 


28
29
30
 
# File 'lib/rubygems/doc_manager.rb', line 28

def rdoc_installed?
  return File.exist?(File.join(@doc_dir, "rdoc"))
end

#run_rdoc(*args) ⇒ Object 



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/rubygems/doc_manager.rb', line 88

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.flatten!

  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
    STDERR.puts "While generating documentation for #{@spec.full_name}"
    STDERR.puts "... MESSAGE:   #{ex}"
    STDERR.puts "... RDOC args: #{args.join(' ')}"
    STDERR.puts ex.backtrace if Gem.configuration.backtrace
    STDERR.puts "(continuing with the rest of the installation)"
  ensure
    Dir.chdir(old_pwd)
  end
end

#uninstall_doc ⇒ Object 



116
117
118
119
120
121
 
# File 'lib/rubygems/doc_manager.rb', line 116

def uninstall_doc
  doc_dir = File.join(@spec.installation_path, "doc", @spec.full_name)
  FileUtils.rm_rf doc_dir
  ri_dir = File.join(@spec.installation_path, "ri", @spec.full_name)
  FileUtils.rm_rf ri_dir
end