Class: Gem::RDoc
- Inherits:
-
Object
- Object
- Gem::RDoc
- 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
-
.rdoc_version ⇒ Object
readonly
Loaded version of RDoc.
Instance Attribute Summary collapse
-
#force ⇒ Object
Force installation of documentation?.
-
#generate_rdoc ⇒ Object
Generate rdoc?.
-
#generate_ri ⇒ Object
Generate ri data?.
Class Method Summary collapse
-
.generation_hook(installer, specs) ⇒ Object
Post installs hook that generates documentation for each specification in
specs
. -
.load_rdoc ⇒ Object
Loads the RDoc generator.
Instance Method Summary collapse
-
#delete_legacy_args(args) ⇒ Object
Removes legacy rdoc arguments from
args
– TODO move to RDoc::Options. -
#document(generator, options, destination) ⇒ Object
Generates documentation using the named
generator
(“darkfish” or “ri”) and following the givenoptions
. -
#generate ⇒ Object
Generates RDoc and ri data.
-
#generate_legacy ⇒ Object
Generates RDoc and ri data for legacy RDoc versions.
-
#initialize(spec, generate_rdoc = true, generate_ri = true) ⇒ RDoc
constructor
Creates a new documentation generator for
spec
. -
#legacy_rdoc(*args) ⇒ Object
Generates RDoc using a legacy version of RDoc from the ARGV-like
args
. -
#new_rdoc ⇒ Object
#new_rdoc creates a new RDoc instance.
-
#rdoc_installed? ⇒ Boolean
Is rdoc documentation installed?.
-
#remove ⇒ Object
Removes generated RDoc and ri data.
-
#ri_installed? ⇒ Boolean
Is ri data installed?.
-
#setup ⇒ Object
Prepares the spec for documentation generation.
Methods included from UserInteraction
alert, alert_error, alert_warning, ask, ask_for_password, ask_yes_no, choose_from_list, say, terminate_interaction, verbose
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.
118 119 120 121 122 123 124 125 126 127 128 129 130 |
# File 'lib/rubygems/rdoc.rb', line 118 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
66 67 68 |
# File 'lib/rubygems/rdoc.rb', line 66 def rdoc_version @rdoc_version end |
Instance Attribute Details
#force ⇒ Object
Force installation of documentation?
49 50 51 |
# File 'lib/rubygems/rdoc.rb', line 49 def force @force end |
#generate_rdoc ⇒ Object
Generate rdoc?
54 55 56 |
# File 'lib/rubygems/rdoc.rb', line 54 def generate_rdoc @generate_rdoc end |
#generate_ri ⇒ Object
Generate ri data?
59 60 61 |
# File 'lib/rubygems/rdoc.rb', line 59 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
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 |
# File 'lib/rubygems/rdoc.rb', line 74 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
96 97 98 99 100 101 102 103 104 105 106 107 108 109 |
# File 'lib/rubygems/rdoc.rb', line 96 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
137 138 139 140 141 142 |
# File 'lib/rubygems/rdoc.rb', line 137 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
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 176 |
# File 'lib/rubygems/rdoc.rb', line 150 def document generator, , destination generator_name = generator = .dup .exclude ||= [] # TODO maybe move to RDoc::Options#finish .setup_generator generator .op_dir = destination .finish generator = .generator.new @rdoc.store, @rdoc. = @rdoc.generator = generator say "Installing #{generator_name} documentation for #{@spec.full_name}" FileUtils.mkdir_p .op_dir Dir.chdir .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
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 231 |
# File 'lib/rubygems/rdoc.rb', line 181 def generate return unless @generate_ri or @generate_rdoc setup = 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. args.concat @spec.source_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 = ::RDoc::Options.new .default_title = "#{@spec.full_name} Documentation" .parse args end .quiet = !Gem.configuration.really_verbose @rdoc = new_rdoc @rdoc. = say "Parsing documentation for #{@spec.full_name}" Dir.chdir @spec.full_gem_path do @file_info = @rdoc.parse_files .files end document 'ri', , @ri_dir if @generate_ri and (@force or not File.exist? @ri_dir) document 'darkfish', , @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.
237 238 239 240 241 242 243 244 245 246 247 248 249 |
# File 'lib/rubygems/rdoc.rb', line 237 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.
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 255 def legacy_rdoc *args args << @spec. 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 verbose { "rdoc #{args.join ' '}" } Dir.chdir @spec.full_gem_path do begin r.document args rescue Errno::EACCES => e dirname = File.dirname e..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)" 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?
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
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?
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
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 |