123456789_123456789_123456789_123456789_123456789_

Class: RDoc::RubygemsHook

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Gem::UserInteraction
Instance Chain:
self, Gem::UserInteraction
Inherits: Object
Defined in: lib/rdoc/rubygems_hook.rb

Overview

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.

Class Attribute Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(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.

[ GitHub ] 

  


# File 'lib/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


  







Class Attribute Details



  

    .rdoc_version   (readonly)
  



  

    

Loaded version of RDoc.  Set by .load_rdoc


  



  [ GitHub ]


  

  


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



attr_reader :rdoc_version


  







Class Method Details



  

    .generation_hook(installer, specs)  
  



  

    

Post installs hook that generates documentation for each specification in specs


  



  [ GitHub ]


  

  


# File 'lib/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  
  



  

    

Loads the RDoc generator


  



  [ GitHub ]


  

  


# File 'lib/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


  







Instance Attribute Details



  

    #force   (rw)
  



  

    

Force installation of documentation?


  



  [ GitHub ]


  

  


# File 'lib/rdoc/rubygems_hook.rb', line 23



attr_accessor :force


  








  

    #generate_rdoc   (rw)
  



  

    

Generate rdoc?


  



  [ GitHub ]


  

  


# File 'lib/rdoc/rubygems_hook.rb', line 28



attr_accessor :generate_rdoc


  








  

    #generate_ri   (rw)
  



  

    

Generate ri data?


  



  [ GitHub ]


  

  


# File 'lib/rdoc/rubygems_hook.rb', line 33



attr_accessor :generate_ri


  








  

    #rdoc_installed?  ⇒ Boolean  (readonly)
  



  

    

Is rdoc documentation installed?


  





  


  [ GitHub ]


  

  


# File 'lib/rdoc/rubygems_hook.rb', line 211



def rdoc_installed?
  File.exist? @rdoc_dir
end


  








  

    #ri_installed?  ⇒ Boolean  (readonly)
  



  

    

Is ri data installed?


  





  


  [ GitHub ]


  

  


# File 'lib/rdoc/rubygems_hook.rb', line 230



def ri_installed?
  File.exist? @ri_dir
end


  







Instance Method Details



  

    #delete_legacy_args(args)  
  



  

    

Removes legacy rdoc arguments from args


  



  [ GitHub ]


  

  


# File 'lib/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)  
  



  

    

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



Documentation will be generated into destination


  



  [ GitHub ]


  

  


# File 'lib/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  
  



  

    

Generates RDoc and ri data


  



  [ GitHub ]


  

  


# File 'lib/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.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
    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
  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


  








  

    #new_rdoc  
  

  

    This method is for internal use only.
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rdoc/rubygems_hook.rb', line 204



def new_rdoc # :nodoc:
  ::RDoc::RDoc.new
end


  








  

    #remove  
  



  

    

Removes generated RDoc and ri data


  





  
Raises:


    
  
  • 
    (Gem::FilePermissionError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/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


  








  

    #setup  
  



  

    

Prepares the spec for documentation generation


  





  
Raises:


    
  
  • 
    (Gem::FilePermissionError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/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