Class: Gem::RDoc

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

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.



108
109
110
111
112
113
114
115
116
117
118
119
120
# File 'lib/rubygems/rdoc.rb', line 108

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_versionObject (readonly)

Loaded version of RDoc. Set by ::load_rdoc



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

def rdoc_version
  @rdoc_version
end

Instance Attribute Details

#forceObject

Force installation of documentation?



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

def force
  @force
end

#generate_rdocObject

Generate rdoc?



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

def generate_rdoc
  @generate_rdoc
end

#generate_riObject

Generate ri data?



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

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



72
73
74
75
76
77
78
79
80
81
# File 'lib/rubygems/rdoc.rb', line 72

def self.generation_hook installer, specs
  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
end

.load_rdocObject

Loads the RDoc generator



86
87
88
89
90
91
92
93
94
95
96
97
98
99
# File 'lib/rubygems/rdoc.rb', line 86

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



127
128
129
130
131
132
# File 'lib/rubygems/rdoc.rb', line 127

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



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
# File 'lib/rubygems/rdoc.rb', line 140

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

#generateObject

Generates RDoc and ri data



171
172
173
174
175
176
177
178
179
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
# File 'lib/rubygems/rdoc.rb', line 171

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_legacyObject

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



227
228
229
230
231
232
233
234
235
236
237
238
239
# File 'lib/rubygems/rdoc.rb', line 227

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.



245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
# File 'lib/rubygems/rdoc.rb', line 245

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_rdocObject

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



282
283
284
# File 'lib/rubygems/rdoc.rb', line 282

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

#rdoc_installed?Boolean

Is rdoc documentation installed?

Returns:

  • (Boolean)


289
290
291
# File 'lib/rubygems/rdoc.rb', line 289

def rdoc_installed?
  File.exist? @rdoc_dir
end

#removeObject

Removes generated RDoc and ri data



296
297
298
299
300
301
302
303
# File 'lib/rubygems/rdoc.rb', line 296

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)


308
309
310
# File 'lib/rubygems/rdoc.rb', line 308

def ri_installed?
  File.exist? @ri_dir
end

#setupObject

Prepares the spec for documentation generation



315
316
317
318
319
320
321
322
# File 'lib/rubygems/rdoc.rb', line 315

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