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 47
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_rdoc() click to toggle source

Loads the RDoc generator

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

  require 'rdoc/rdoc'

  @rdoc_version = Gem::Version.new ::RDoc::VERSION
end

new(spec, generate_rdoc = true, generate_ri = true) click to toggle source

Creates a new documentation generator for spec. RDoc and ri data generation can be disabled through generate_rdoc and generate_ri respectively.

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

Public Instance Methods

delete_legacy_args(args) click to toggle source

Removes legacy rdoc arguments from args

 
               # File rdoc/rubygems_hook.rb, line 93
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 106
def document generator, options, destination
  options = options.dup
  options.exclude ||= [] # TODO maybe move to RDoc::Options#finish
  options.setup_generator generator
  options.op_dir = destination
  options.finish

  @rdoc.options = options
  @rdoc.generator = options.generator.new options

  say "Installing #{generator} 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

generate() click to toggle source

Generates RDoc and ri data

 
               # File rdoc/rubygems_hook.rb, line 133
def generate
  return unless @generate_ri or @generate_rdoc

  setup

  ::RDoc::RDoc.reset

  options = ::RDoc::Options.new
  options.default_title = "#{@spec.full_name} Documentation"
  options.files = []
  options.files.push(*@spec.require_paths)
  options.files.push(*@spec.extra_rdoc_files)

  args = @spec.rdoc_options

  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
  options.parse args
  options.quiet = !Gem.configuration.really_verbose

  @rdoc = new_rdoc
  @rdoc.options = options

  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

rdoc_installed?() click to toggle source

Is rdoc documentation installed?

 
               # File rdoc/rubygems_hook.rb, line 184
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 191
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 203
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 210
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 see Improve the docs, or visit Documenting-ruby.org.

Home Classes Methods

In Files

Parent

Methods

Included Modules

Class/Module Index

RDoc::RubygemsHook

Attributes

Public Class Methods

Public Instance Methods