Class: Gem::DocManager
- Inherits:
-
Object
- Object
- Gem::DocManager
- Includes:
- UserInteraction
- Defined in:
- lib/rubygems/doc_manager.rb
Overview
The documentation manager generates RDoc and RI for RubyGems.
Class Method Summary collapse
- .configured_args ⇒ Object
- .configured_args=(args) ⇒ Object
-
.load_rdoc ⇒ Object
Load RDoc from a gem if it is available, otherwise from Ruby’s stdlib.
- .rdoc_version ⇒ Object
-
.update_ri_cache ⇒ Object
Updates the RI cache for RDoc 2 if it is installed.
Instance Method Summary collapse
-
#generate_rdoc ⇒ Object
Generate the RDoc documents for this gem spec.
-
#generate_ri ⇒ Object
Generate the RI documents for this gem spec.
-
#initialize(spec, rdoc_args = "") ⇒ DocManager
constructor
Create a document manager for
spec
. -
#install_rdoc ⇒ Object
Generate and install RDoc into the documentation directory.
-
#install_ri ⇒ Object
Generate and install RI into the documentation directory.
-
#rdoc_installed? ⇒ Boolean
Is the RDoc documentation installed?.
-
#ri_installed? ⇒ Boolean
Is the RI documentation installed?.
-
#run_rdoc(*args) ⇒ Object
Run RDoc with
args
, which is an ARGV style argument list. - #setup_rdoc ⇒ Object
-
#uninstall_doc ⇒ Object
Remove RDoc and RI documentation.
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, rdoc_args = "") ⇒ DocManager
Create a document manager for spec
. rdoc_args
contains arguments for RDoc (template etc.) as a String.
86 87 88 89 90 91 |
# File 'lib/rubygems/doc_manager.rb', line 86 def initialize(spec, rdoc_args="") require 'fileutils' @spec = spec @doc_dir = spec.doc_dir @rdoc_args = rdoc_args.nil? ? [] : rdoc_args.split end |
Class Method Details
.configured_args ⇒ Object
18 19 20 |
# File 'lib/rubygems/doc_manager.rb', line 18 def self.configured_args @configured_args ||= [] end |
.configured_args=(args) ⇒ Object
22 23 24 25 26 27 28 29 |
# File 'lib/rubygems/doc_manager.rb', line 22 def self.configured_args=(args) case args when Array @configured_args = args when String @configured_args = args.split end end |
.load_rdoc ⇒ Object
Load RDoc from a gem if it is available, otherwise from Ruby’s stdlib
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
# File 'lib/rubygems/doc_manager.rb', line 34 def self.load_rdoc begin gem 'rdoc' rescue Gem::LoadError # use built-in RDoc end begin require 'rdoc/rdoc' @rdoc_version = if defined? RDoc::VERSION then Gem::Version.new RDoc::VERSION else Gem::Version.new '1.0.1' # HACK parsing is hard end rescue LoadError => e raise Gem::DocumentError, "ERROR: RDoc documentation generator not installed: #{e}" end end |
.rdoc_version ⇒ Object
56 57 58 |
# File 'lib/rubygems/doc_manager.rb', line 56 def self.rdoc_version @rdoc_version end |
.update_ri_cache ⇒ Object
Updates the RI cache for RDoc 2 if it is installed
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 |
# File 'lib/rubygems/doc_manager.rb', line 63 def self.update_ri_cache load_rdoc rescue return return unless defined? RDoc::VERSION # RDoc 1 does not have VERSION require 'rdoc/ri/driver' = { :use_cache => true, :use_system => true, :use_site => true, :use_home => true, :use_gems => true, :formatter => RDoc::RI::Formatter, } RDoc::RI::Driver.new().class_cache 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).
128 129 130 131 132 133 |
# File 'lib/rubygems/doc_manager.rb', line 128 def generate_rdoc setup_rdoc install_rdoc 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).
114 115 116 117 118 119 |
# File 'lib/rubygems/doc_manager.rb', line 114 def generate_ri setup_rdoc install_ri # RDoc bug, ri goes first FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) end |
#install_rdoc ⇒ Object
Generate and install RDoc into the documentation directory
138 139 140 141 142 143 144 145 |
# File 'lib/rubygems/doc_manager.rb', line 138 def install_rdoc rdoc_dir = File.join @doc_dir, 'rdoc' FileUtils.rm_rf rdoc_dir say "Installing RDoc documentation for #{@spec.full_name}..." run_rdoc '--op', rdoc_dir end |
#install_ri ⇒ Object
Generate and install RI into the documentation directory
150 151 152 153 154 155 156 157 |
# File 'lib/rubygems/doc_manager.rb', line 150 def install_ri ri_dir = File.join @doc_dir, 'ri' FileUtils.rm_rf ri_dir say "Installing ri documentation for #{@spec.full_name}..." run_rdoc '--ri', '--op', ri_dir end |
#rdoc_installed? ⇒ Boolean
Is the RDoc documentation installed?
96 97 98 |
# File 'lib/rubygems/doc_manager.rb', line 96 def rdoc_installed? File.exist?(File.join(@doc_dir, "rdoc")) end |
#ri_installed? ⇒ Boolean
Is the RI documentation installed?
103 104 105 |
# File 'lib/rubygems/doc_manager.rb', line 103 def ri_installed? File.exist?(File.join(@doc_dir, "ri")) end |
#run_rdoc(*args) ⇒ Object
Run RDoc with args
, which is an ARGV style argument list
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 |
# File 'lib/rubygems/doc_manager.rb', line 162 def run_rdoc(*args) args << @spec. args << self.class.configured_args args << @spec.require_paths.clone args << @spec.extra_rdoc_files args << '--title' << "#{@spec.full_name} Documentation" args << '--quiet' args = args.flatten.map do |arg| arg.to_s end if self.class.rdoc_version >= Gem::Version.new('2.4.0') then args.delete '--inline-source' args.delete '--promiscuous' args.delete '-p' args.delete '--one-file' # HACK more end debug_args = args.dup r = RDoc::RDoc.new old_pwd = Dir.pwd Dir.chdir @spec.full_gem_path say "rdoc #{args.join ' '}" if Gem.configuration.really_verbose begin r.document args rescue Errno::EACCES => e dirname = File.dirname e..split("-")[1].strip raise Gem::FilePermissionError.new(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: #{debug_args.join(' ')}" ui.errs.puts "\t#{ex.backtrace.join "\n\t"}" if Gem.configuration.backtrace terminate_interaction 1 ensure Dir.chdir old_pwd end end |
#setup_rdoc ⇒ Object
207 208 209 210 211 212 213 214 215 |
# File 'lib/rubygems/doc_manager.rb', line 207 def setup_rdoc if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then raise Gem::FilePermissionError.new(@doc_dir) end FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir) self.class.load_rdoc end |
#uninstall_doc ⇒ Object
Remove RDoc and RI documentation
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 |
# File 'lib/rubygems/doc_manager.rb', line 220 def uninstall_doc base_dir = @spec.base_dir raise Gem::FilePermissionError.new base_dir unless File.writable? base_dir # TODO: ok... that's twice... ugh old_name = [ @spec.name, @spec.version, @spec.original_platform].join '-' doc_dir = @spec.doc_dir unless File.directory? doc_dir then doc_dir = File.join File.dirname(doc_dir), old_name end ri_dir = @spec.ri_dir unless File.directory? ri_dir then ri_dir = File.join File.dirname(ri_dir), old_name end FileUtils.rm_rf doc_dir FileUtils.rm_rf ri_dir end |