Class: RDoc::RubyGemsHook

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

Overview

We define the following two similar name classes in this file:

  • RDoc::RubyGemsHook
  • RDoc::RubygemsHook

RDoc::RubyGemsHook is the main class that has real logic.

RDoc::RubygemsHook is a class that is only for compatibility. RDoc::RubygemsHook is used by RubyGems directly. We can remove this when all maintained RubyGems remove rubygems/rdoc.rb.

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(spec, generate_rdoc = false, generate_ri = true) ⇒ RubyGemsHook

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.



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

def initialize(spec, generate_rdoc = false, generate_ri = true)
  @doc_dir   = spec.doc_dir
  @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



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

def rdoc_version
  @rdoc_version
end

Instance Attribute Details

#force ⇒ Object

Force installation of documentation?



30
31
32
 
# File 'lib/rdoc/rubygems_hook.rb', line 30

def force
  @force
end

#generate_rdoc ⇒ Object

Generate rdoc?



35
36
37
 
# File 'lib/rdoc/rubygems_hook.rb', line 35

def generate_rdoc
  @generate_rdoc
end

#generate_ri ⇒ Object

Generate ri data?



40
41
42
 
# File 'lib/rdoc/rubygems_hook.rb', line 40

def generate_ri
  @generate_ri
end

Class Method Details

.generate(installer, specs) ⇒ Object

Post installs hook that generates documentation for each specification in specs



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/rdoc/rubygems_hook.rb', line 55

def self.generate(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



81
82
83
84
85
86
87
 
# File 'lib/rdoc/rubygems_hook.rb', line 81

def self.load_rdoc
  return if @rdoc_version

  require_relative 'rdoc'

  @rdoc_version = Gem::Version.new VERSION
end

.remove(uninstaller) ⇒ Object 



74
75
76
 
# File 'lib/rdoc/rubygems_hook.rb', line 74

def self.remove(uninstaller)
  new(uninstaller.spec).remove
end

Instance Method Details

#delete_legacy_args(args) ⇒ Object

Removes legacy rdoc arguments from args

TODO move to RDoc::Options



114
115
116
117
118
119
 
# File 'lib/rdoc/rubygems_hook.rb', line 114

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 ("aliki" or "ri") and following the given options.

Documentation will be generated into destination



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/rdoc/rubygems_hook.rb', line 127

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
  Dir.chdir @spec.full_gem_path do
    options.finish
  end

  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
    ensure
      @rdoc.class.current = nil
    end
  end
end

#generate ⇒ Object

Generates RDoc and ri data



160
161
162
163
164
165
166
167
168
169
170
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
 
# File 'lib/rdoc/rubygems_hook.rb', line 160

def generate
  return if @spec.default_gem?
  return unless @generate_ri or @generate_rdoc

  setup

  options = nil

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

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

  delete_legacy_args args

  Dir.chdir @spec.full_gem_path do
    options = Options.new
    options.default_title = "#{@spec.full_name} Documentation"
    options.parse args
    options.quiet = !Gem.configuration.really_verbose
  end

  @rdoc = new_rdoc

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

  Dir.chdir @spec.full_gem_path do
    # RDoc::Options#finish must be called before parse_files.
    # RDoc::Options#finish is also called after ri/aliki generator setup.
    # We need to dup the options to avoid modifying it after finish is called.
    parse_options = options.dup
    parse_options.finish
    @rdoc.options = parse_options
    @rdoc.store = Store.new(parse_options)
    @rdoc.parse_files parse_options.files
  end

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

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

#new_rdoc ⇒ Object

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



214
215
216
 
# File 'lib/rdoc/rubygems_hook.rb', line 214

def new_rdoc # :nodoc:
  RDoc.new
end

#rdoc_installed? ⇒ Boolean

Is rdoc documentation installed?

Returns:

  • (Boolean) 


221
222
223
 
# File 'lib/rdoc/rubygems_hook.rb', line 221

def rdoc_installed?
  File.exist? @rdoc_dir
end

#remove ⇒ Object

Removes generated RDoc and ri data

Raises:

  • (Gem::FilePermissionError) 


228
229
230
231
232
233
234
235
 
# File 'lib/rdoc/rubygems_hook.rb', line 228

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) 


240
241
242
 
# File 'lib/rdoc/rubygems_hook.rb', line 240

def ri_installed?
  File.exist? @ri_dir
end

#setup ⇒ Object

Prepares the spec for documentation generation

Raises:

  • (Gem::FilePermissionError) 


247
248
249
250
251
252
253
254
 
# File 'lib/rdoc/rubygems_hook.rb', line 247

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