In Files

  • rdoc/rubygems_hook.rb

Class/Module Index [+]

Quicksearch

RDoc::RubygemsHook

Gem::RDoc provides methods to generate RDoc and ri data for installed gems upon gem installation.

This file is automatically required by RubyGems 1.9 and newer.

Attributes

rdoc_version[R]

Loaded version of RDoc. Set by ::load_rdoc

force[RW]

Force installation of documentation?

generate_rdoc[RW]

Generate rdoc?

generate_ri[RW]

Generate ri data?

Public Class Methods

generation_hook(installer, specs) click to toggle source

Post installs hook that generates documentation for each specification in specs

 
               # File rdoc/rubygems_hook.rb, line 48
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() click to toggle source

Loads the RDoc generator

 
               # File rdoc/rubygems_hook.rb, line 70
def self.load_rdoc
  return if @rdoc_version

  require 'rdoc/rdoc'

  @rdoc_version = Gem::Version.new ::RDoc::VERSION
end
            
new(spec, generate_rdoc = false, generate_ri = true) click to toggle source

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.

 
               # File rdoc/rubygems_hook.rb, line 85
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
            

Public Instance Methods

delete_legacy_args(args) click to toggle source

Removes legacy rdoc arguments from args

 
               # File rdoc/rubygems_hook.rb, line 103
def delete_legacy_args args
  args.delete '--inline-source'
  args.delete '--promiscuous'
  args.delete '-p'
  args.delete '--one-file'
end
            
document(generator, options, destination) click to toggle source

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

Documentation will be generated into destination

 
               # File rdoc/rubygems_hook.rb, line 116
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
    ensure
      @rdoc.class.current = nil
    end
  end
end
            
generate() click to toggle source

Generates RDoc and ri data

 
               # File rdoc/rubygems_hook.rb, line 147
def generate
  return if @spec.default_gem?
  return unless @generate_ri or @generate_rdoc

  setup

  options = nil

  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

  store = RDoc::Store.new
  store.encoding = options.encoding if options.respond_to? :encoding
  store.dry_run  = options.dry_run
  store.main     = options.main_page
  store.title    = options.title

  @rdoc.store = store

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

  Dir.chdir @spec.full_gem_path do
    @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
            
rdoc_installed?() click to toggle source

Is rdoc documentation installed?

 
               # File rdoc/rubygems_hook.rb, line 211
def rdoc_installed?
  File.exist? @rdoc_dir
end
            
remove() click to toggle source

Removes generated RDoc and ri data

 
               # File rdoc/rubygems_hook.rb, line 218
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?() click to toggle source

Is ri data installed?

 
               # File rdoc/rubygems_hook.rb, line 230
def ri_installed?
  File.exist? @ri_dir
end
            
setup() click to toggle source

Prepares the spec for documentation generation

 
               # File rdoc/rubygems_hook.rb, line 237
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
            

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

blog comments powered by Disqus