Class: Gem::RDoc

Inherits:
Object
  • Object
show all
Extended by:
UserInteraction
Includes:
UserInteraction
Defined in:
lib/rubygems/rdoc.rb

Overview

Gem::RDoc provides methods to generate RDoc and ri data for installed gems. It works for RDoc 1.0.1 (in Ruby 1.8) up to RDoc 3.6.

This implementation is considered obsolete. The RDoc project is the appropriate location to find this functionality. This file provides the hooks to load RDoc generation code from the “rdoc” gem and a fallback in case the installed version of RDoc does not have them.

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from UserInteraction

alert, alert_error, alert_warning, ask, ask_for_password, ask_yes_no, choose_from_list, say, terminate_interaction

Methods included from DefaultUserInteraction

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

Constructor Details

#initialize(spec, generate_rdoc = true, generate_ri = true) ⇒ RDoc

Creates a new documentation generator for spec. RDoc and ri data generation can be enabled or disabled through generate_rdoc and generate_ri respectively.

Only generate_ri is enabled by default.



117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/rubygems/rdoc.rb', line 117

def initialize spec, generate_rdoc = true, generate_ri = true
  @doc_dir   = spec.doc_dir
  @file_info = nil
  @force     = false
  @rdoc      = nil
  @spec      = spec

  @generate_rdoc = generate_rdoc
  @generate_ri   = generate_ri

  @rdoc_dir = spec.doc_dir 'rdoc'
  @ri_dir   = spec.doc_dir 'ri'
end

Class Attribute Details

.rdoc_version ⇒ Object (readonly)

Loaded version of RDoc. Set by ::load_rdoc



65
66
67
 
# File 'lib/rubygems/rdoc.rb', line 65

def rdoc_version
  @rdoc_version
end

Instance Attribute Details

#force ⇒ Object

Force installation of documentation?



48
49
50
 
# File 'lib/rubygems/rdoc.rb', line 48

def force
  @force
end

#generate_rdoc ⇒ Object

Generate rdoc?



53
54
55
 
# File 'lib/rubygems/rdoc.rb', line 53

def generate_rdoc
  @generate_rdoc
end

#generate_ri ⇒ Object

Generate ri data?



58
59
60
 
# File 'lib/rubygems/rdoc.rb', line 58

def generate_ri
  @generate_ri
end

Class Method Details

.generation_hook(installer, specs) ⇒ Object

Post installs hook that generates documentation for each specification in specs



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/rubygems/rdoc.rb', line 73

def self.generation_hook installer, specs
  start = Time.now
  types = installer.document

  generate_rdoc = types.include? 'rdoc'
  generate_ri   = types.include? 'ri'

  specs.each do |spec|
    new(spec, generate_rdoc, generate_ri).generate
  end

  return unless generate_rdoc or generate_ri

  duration = (Time.now - start).to_i
  names    = specs.map(&:name).join ', '

  say "Done installing documentation for #{names} after #{duration} seconds"
end

.load_rdoc ⇒ Object

Loads the RDoc generator



95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/rubygems/rdoc.rb', line 95

def self.load_rdoc
  return if @rdoc_version

  require 'rdoc/rdoc'

  @rdoc_version = if ::RDoc.const_defined? :VERSION then
                    Gem::Version.new ::RDoc::VERSION
                  else
                    Gem::Version.new '1.0.1'
                  end

rescue LoadError => e
  raise Gem::DocumentError, "RDoc is not installed: #{e}"
end

Instance Method Details

#delete_legacy_args(args) ⇒ Object

Removes legacy rdoc arguments from args – TODO move to RDoc::Options



136
137
138
139
140
141
 
# File 'lib/rubygems/rdoc.rb', line 136

def delete_legacy_args args
  args.delete '--inline-source'
  args.delete '--promiscuous'
  args.delete '-p'
  args.delete '--one-file'
end

#document(generator, options, destination) ⇒ Object

Generates documentation using the named generator (“darkfish” or “ri”) and following the given options.

Documentation will be generated into destination



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/rubygems/rdoc.rb', line 149

def document generator, options, destination
  generator_name = generator

  options = options.dup
  options.exclude ||= [] # TODO maybe move to RDoc::Options#finish
  options.setup_generator generator
  options.op_dir = destination
  options.finish

  generator = options.generator.new @rdoc.store, options

  @rdoc.options = options
  @rdoc.generator = generator

  say "Installing #{generator_name} documentation for #{@spec.full_name}"

  FileUtils.mkdir_p options.op_dir

  Dir.chdir options.op_dir do
    begin
      @rdoc.class.current = @rdoc
      @rdoc.generator.generate @file_info
    ensure
      @rdoc.class.current = nil
    end
  end
end

#generate ⇒ Object

Generates RDoc and ri data



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/rubygems/rdoc.rb', line 180

def generate
  return unless @generate_ri or @generate_rdoc

  setup

  options = nil

  if Gem::Requirement.new('< 3').satisfied_by? self.class.rdoc_version then
    generate_legacy
    return
  end

  ::RDoc::TopLevel.reset # TODO ::RDoc::RDoc.reset
  ::RDoc::Parser::C.reset

  args = @spec.rdoc_options
  args.concat @spec.require_paths
  args.concat @spec.extra_rdoc_files

  case config_args = Gem.configuration[:rdoc]
  when String then
    args = args.concat config_args.split
  when Array then
    args = args.concat config_args
  end

  delete_legacy_args args

  Dir.chdir @spec.full_gem_path do
    options = ::RDoc::Options.new
    options.default_title = "#{@spec.full_name} Documentation"
    options.parse args
  end

  options.quiet = !Gem.configuration.really_verbose

  @rdoc = new_rdoc
  @rdoc.options = options

  say "Parsing documentation for #{@spec.full_name}"

  Dir.chdir @spec.full_gem_path do
    @file_info = @rdoc.parse_files options.files
  end

  document 'ri',       options, @ri_dir if
    @generate_ri   and (@force or not File.exist? @ri_dir)

  document 'darkfish', options, @rdoc_dir if
    @generate_rdoc and (@force or not File.exist? @rdoc_dir)
end

#generate_legacy ⇒ Object

Generates RDoc and ri data for legacy RDoc versions. This method will not exist in future versions.



236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/rubygems/rdoc.rb', line 236

def generate_legacy
  if @generate_rdoc then
    FileUtils.rm_rf @rdoc_dir
    say "Installing RDoc documentation for #{@spec.full_name}"
    legacy_rdoc '--op', @rdoc_dir
  end

  if @generate_ri then
    FileUtils.rm_rf @ri_dir
    say "Installing ri documentation for #{@spec.full_name}"
    legacy_rdoc '--ri', '--op', @ri_dir
  end
end

#legacy_rdoc(*args) ⇒ Object

Generates RDoc using a legacy version of RDoc from the ARGV-like args. This method will not exist in future versions.



254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
 
# File 'lib/rubygems/rdoc.rb', line 254

def legacy_rdoc *args
  args << @spec.rdoc_options
  args << '--quiet'
  args << @spec.require_paths.clone
  args << @spec.extra_rdoc_files
  args << '--title' << "#{@spec.full_name} Documentation"
  args = args.flatten.map do |arg| arg.to_s end

  delete_legacy_args args if
    Gem::Requirement.new('>= 2.4.0') =~ self.class.rdoc_version

  r = new_rdoc
  say "rdoc #{args.join ' '}" if Gem.configuration.really_verbose

  Dir.chdir @spec.full_gem_path do
    begin
      r.document args
    rescue Errno::EACCES => e
      dirname = File.dirname e.message.split("-")[1].strip
      raise Gem::FilePermissionError, 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: #{args.join(' ')}"
      ui.backtrace ex
      ui.errs.puts "(continuing with the rest of the installation)"
    ensure
    end
  end
end

#new_rdoc ⇒ Object

#new_rdoc creates a new RDoc instance. This method is provided only to make testing easier.



291
292
293
 
# File 'lib/rubygems/rdoc.rb', line 291

def new_rdoc # :nodoc:
  ::RDoc::RDoc.new
end

#rdoc_installed? ⇒ Boolean

Is rdoc documentation installed?

Returns:

  • (Boolean) 


298
299
300
 
# File 'lib/rubygems/rdoc.rb', line 298

def rdoc_installed?
  File.exist? @rdoc_dir
end

#remove ⇒ Object

Removes generated RDoc and ri data

Raises:



305
306
307
308
309
310
311
312
 
# File 'lib/rubygems/rdoc.rb', line 305

def remove
  base_dir = @spec.base_dir

  raise Gem::FilePermissionError, base_dir unless File.writable? base_dir

  FileUtils.rm_rf @rdoc_dir
  FileUtils.rm_rf @ri_dir
end

#ri_installed? ⇒ Boolean

Is ri data installed?

Returns:

  • (Boolean) 


317
318
319
 
# File 'lib/rubygems/rdoc.rb', line 317

def ri_installed?
  File.exist? @ri_dir
end

#setup ⇒ Object

Prepares the spec for documentation generation

Raises:



324
325
326
327
328
329
330
331
 
# File 'lib/rubygems/rdoc.rb', line 324

def setup
  self.class.load_rdoc

  raise Gem::FilePermissionError, @doc_dir if
    File.exist?(@doc_dir) and not File.writable?(@doc_dir)

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