class RDoc::RubygemsHook - rdoc-4.1.2 Documentation

# class 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 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() click to toggle source

Loads the RDoc generator

    # 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

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 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

### Public Instance Methods

delete_legacy_args(args) click to toggle source

Removes legacy rdoc arguments from `args`

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

Generates RDoc and ri data

    # 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

      if @spec.respond_to? :source_paths then
        args.concat @spec.source_paths
      else
        args.concat @spec.require_paths
      end

      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 lib/rdoc/rubygems_hook.rb, line 217
    def rdoc_installed?
      File.exist? @rdoc_dir
    end

remove() click to toggle source

Removes generated RDoc and ri data

    # File lib/rdoc/rubygems_hook.rb, line 224
    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 lib/rdoc/rubygems_hook.rb, line 236
    def ri_installed?
      File.exist? @ri_dir
    end

setup() click to toggle source

Prepares the spec for documentation generation

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